From d76a346376c6d19560a59f06e756c52dfd3d3839 Mon Sep 17 00:00:00 2001 From: Mutahhar Mustafa Khan <94354732+mutahharmkhan@users.noreply.github.com> Date: Mon, 20 Apr 2026 13:05:57 +0100 Subject: [PATCH] docs(examples): introduce summary and description to examples (#9968) Co-authored-by: Gabor Kiss-Vamosi --- examples/about.md | 6 ++++++ examples/anim/about.md | 7 +++++++ examples/anim/lv_example_anim_2.c | 10 +++++++++- examples/anim/lv_example_anim_3.c | 19 +++++++++++-------- examples/anim/lv_example_anim_4.c | 10 +++++++++- examples/anim/lv_example_anim_timeline_1.c | 13 ++++++++++++- examples/event/about.md | 7 +++++++ examples/event/lv_example_event_bubble.c | 9 ++++++++- examples/event/lv_example_event_button.c | 9 ++++++++- examples/event/lv_example_event_draw.c | 10 +++++++++- examples/event/lv_example_event_streak.c | 2 -- examples/event/lv_example_event_trickle.c | 10 +++++++++- examples/get_started/about.md | 7 +++++++ .../get_started/lv_example_get_started_2.c | 8 +++++++- .../get_started/lv_example_get_started_3.c | 11 ++++++++++- .../get_started/lv_example_get_started_4.c | 8 +++++++- examples/grad/about.md | 7 +++++++ examples/grad/lv_example_grad_1.c | 13 +++++++++++-- examples/grad/lv_example_grad_2.c | 15 +++++++++++++-- examples/grad/lv_example_grad_3.c | 16 +++++++++++++--- examples/grad/lv_example_grad_4.c | 13 ++++++++++++- examples/layouts/about.md | 7 +++++++ examples/layouts/flex/about.md | 6 ++++++ examples/layouts/flex/lv_example_flex_2.c | 9 ++++++++- examples/layouts/flex/lv_example_flex_3.c | 9 ++++++++- examples/layouts/flex/lv_example_flex_4.c | 8 +++++++- examples/layouts/flex/lv_example_flex_5.c | 9 ++++++++- examples/layouts/flex/lv_example_flex_6.c | 10 ++++++++-- examples/layouts/grid/about.md | 6 ++++++ examples/layouts/grid/lv_example_grid_1.c | 9 ++++++++- examples/layouts/grid/lv_example_grid_2.c | 9 ++++++++- examples/layouts/grid/lv_example_grid_4.c | 9 ++++++++- examples/layouts/grid/lv_example_grid_5.c | 9 ++++++++- examples/layouts/grid/lv_example_grid_6.c | 9 ++++++++- examples/libs/about.md | 7 +++++++ examples/libs/barcode/about.md | 6 ++++++ examples/libs/barcode/lv_example_barcode_1.c | 9 ++++++++- examples/libs/bmp/about.md | 6 ++++++ examples/libs/bmp/lv_example_bmp_1.c | 8 +++++++- examples/libs/ffmpeg/about.md | 6 ++++++ examples/libs/ffmpeg/lv_example_ffmpeg_1.c | 9 ++++++++- examples/libs/ffmpeg/lv_example_ffmpeg_2.c | 9 ++++++++- examples/libs/freetype/about.md | 6 ++++++ .../libs/freetype/lv_example_freetype_1.c | 10 +++++++++- .../libs/freetype/lv_example_freetype_2.c | 9 ++++++++- .../libs/freetype/lv_example_freetype_3.c | 10 +++++++++- examples/libs/gif/about.md | 6 ++++++ examples/libs/gif/lv_example_gif_1.c | 9 ++++++++- examples/libs/gltf/about.md | 6 ++++++ examples/libs/gltf/lv_example_gltf_1.c | 10 +++++++++- examples/libs/gltf/lv_example_gltf_2.c | 11 ++++++++++- examples/libs/gltf/lv_example_gltf_3.c | 13 ++++++++++++- examples/libs/gltf/lv_example_gltf_4.c | 14 +++++++++++--- examples/libs/gstreamer/about.md | 6 ++++++ .../libs/gstreamer/lv_example_gstreamer_1.c | 14 +++++++++++++- examples/libs/libjpeg_turbo/about.md | 6 ++++++ .../lv_example_libjpeg_turbo_1.c | 8 +++++++- examples/libs/libpng/about.md | 6 ++++++ examples/libs/libpng/lv_example_libpng_1.c | 9 ++++++++- examples/libs/libwebp/about.md | 6 ++++++ examples/libs/libwebp/lv_example_libwebp_1.c | 8 +++++++- examples/libs/lodepng/about.md | 6 ++++++ examples/libs/lodepng/lv_example_lodepng_1.c | 9 ++++++++- examples/libs/qrcode/about.md | 6 ++++++ examples/libs/qrcode/lv_example_qrcode_1.c | 9 ++++++++- examples/libs/rlottie/about.md | 6 ++++++ examples/libs/rlottie/lv_example_rlottie_1.c | 7 ++++++- examples/libs/rlottie/lv_example_rlottie_2.c | 9 ++++++++- examples/libs/svg/about.md | 6 ++++++ examples/libs/svg/lv_example_svg_1.c | 9 ++++++++- examples/libs/svg/lv_example_svg_2.c | 7 ++++++- examples/libs/svg/lv_example_svg_3.c | 10 ++++++++++ examples/libs/tiny_ttf/about.md | 6 ++++++ .../libs/tiny_ttf/lv_example_tiny_ttf_1.c | 8 +++++++- .../libs/tiny_ttf/lv_example_tiny_ttf_2.c | 9 ++++++++- .../libs/tiny_ttf/lv_example_tiny_ttf_3.c | 10 +++++++++- examples/libs/tjpgd/about.md | 6 ++++++ examples/libs/tjpgd/lv_example_tjpgd_1.c | 7 ++++++- examples/others/about.md | 7 +++++++ examples/others/file_explorer/about.md | 6 ++++++ .../lv_example_file_explorer_1.c | 11 +++++++++++ .../lv_example_file_explorer_2.c | 12 ++++++++++++ .../lv_example_file_explorer_3.c | 10 ++++++++++ examples/others/font_manager/about.md | 6 ++++++ .../font_manager/lv_example_font_manager_1.c | 11 +++++++++++ .../font_manager/lv_example_font_manager_2.c | 12 ++++++++++++ .../font_manager/lv_example_font_manager_3.c | 12 ++++++++++++ examples/others/fragment/about.md | 6 ++++++ .../others/fragment/lv_example_fragment_1.c | 10 ++++++++++ .../others/fragment/lv_example_fragment_2.c | 12 ++++++++++++ examples/others/gestures/about.md | 6 ++++++ .../others/gestures/lv_example_gestures.c | 12 ++++++++++-- examples/others/gridnav/about.md | 6 ++++++ .../others/gridnav/lv_example_gridnav_1.c | 10 +++++++++- .../others/gridnav/lv_example_gridnav_2.c | 9 ++++++++- .../others/gridnav/lv_example_gridnav_3.c | 11 ++++++++++- .../others/gridnav/lv_example_gridnav_4.c | 10 +++++++++- .../others/gridnav/lv_example_gridnav_5.c | 10 +++++++++- examples/others/ime/about.md | 6 ++++++ examples/others/ime/lv_example_ime_pinyin_1.c | 12 ++++++++++++ examples/others/ime/lv_example_ime_pinyin_2.c | 11 +++++++++++ examples/others/imgfont/about.md | 6 ++++++ .../others/imgfont/lv_example_imgfont_1.c | 9 ++++++++- examples/others/monkey/about.md | 6 ++++++ examples/others/monkey/lv_example_monkey_1.c | 9 +++++++++ examples/others/monkey/lv_example_monkey_2.c | 9 +++++++++ examples/others/monkey/lv_example_monkey_3.c | 10 ++++++++++ examples/others/observer/about.md | 6 ++++++ .../others/observer/lv_example_observer_1.c | 9 ++++++++- .../others/observer/lv_example_observer_2.c | 13 +++++++++++-- .../others/observer/lv_example_observer_3.c | 16 +++++++++++----- .../others/observer/lv_example_observer_4.c | 12 ++++++++++++ .../others/observer/lv_example_observer_5.c | 17 ++++++++++++----- .../others/observer/lv_example_observer_6.c | 11 ++++++++++- .../others/observer/lv_example_observer_7.c | 12 +++++++++++- examples/others/snapshot/about.md | 6 ++++++ .../others/snapshot/lv_example_snapshot_1.c | 12 ++++++++++++ examples/others/translation/about.md | 6 ++++++ .../translation/lv_example_translation_1.c | 11 ++++++++++- .../translation/lv_example_translation_2.c | 10 +++++++++- examples/porting/about.md | 8 ++++++++ examples/porting/osal/about.md | 6 ++++++ examples/porting/osal/lv_example_osal.c | 12 ++++++++++++ examples/scroll/about.md | 7 +++++++ examples/scroll/lv_example_scroll_1.c | 9 ++++++++- examples/scroll/lv_example_scroll_2.c | 9 ++++++++- examples/scroll/lv_example_scroll_3.c | 10 +++++++++- examples/scroll/lv_example_scroll_4.c | 10 +++++++++- examples/scroll/lv_example_scroll_5.c | 8 +++++++- examples/scroll/lv_example_scroll_6.c | 11 ++++++++++- examples/scroll/lv_example_scroll_7.c | 11 ++++++++++- examples/scroll/lv_example_scroll_8.c | 12 ++++++++++++ examples/scroll/lv_example_scroll_9.c | 11 +++++++++++ examples/styles/about.md | 7 +++++++ examples/styles/lv_example_style_1.c | 9 ++++++++- examples/styles/lv_example_style_10.c | 9 ++++++++- examples/styles/lv_example_style_11.c | 10 +++++++++- examples/styles/lv_example_style_12.c | 10 +++++++++- examples/styles/lv_example_style_13.c | 9 ++++++++- examples/styles/lv_example_style_14.c | 9 ++++++++- examples/styles/lv_example_style_15.c | 12 +++++++++++- examples/styles/lv_example_style_16.c | 10 +++++++++- examples/styles/lv_example_style_17.c | 12 ++++++++++-- examples/styles/lv_example_style_18.c | 11 ++++++++++- examples/styles/lv_example_style_19.c | 12 +++++++++++- examples/styles/lv_example_style_2.c | 8 +++++++- examples/styles/lv_example_style_20.c | 11 ++++++++++- examples/styles/lv_example_style_21.c | 14 ++++++++++++++ examples/styles/lv_example_style_3.c | 8 +++++++- examples/styles/lv_example_style_4.c | 8 +++++++- examples/styles/lv_example_style_5.c | 7 ++++++- examples/styles/lv_example_style_6.c | 8 +++++++- examples/styles/lv_example_style_7.c | 7 ++++++- examples/styles/lv_example_style_8.c | 9 ++++++++- examples/styles/lv_example_style_9.c | 8 +++++++- examples/widgets/about.md | 7 +++++++ examples/widgets/animimg/about.md | 4 ++++ .../widgets/animimg/lv_example_animimg_1.c | 11 +++++++++++ examples/widgets/arc/about.md | 4 ++++ examples/widgets/arc/lv_example_arc_1.c | 11 +++++++++++ examples/widgets/arc/lv_example_arc_2.c | 9 ++++++++- examples/widgets/arc/lv_example_arc_3.c | 14 ++++++++++++++ examples/widgets/arclabel/about.md | 6 ++++++ .../widgets/arclabel/lv_example_arclabel_1.c | 14 ++++++++++++++ examples/widgets/bar/about.md | 4 ++++ examples/widgets/bar/lv_example_bar_1.c | 9 +++++++++ examples/widgets/bar/lv_example_bar_2.c | 10 +++++++++- examples/widgets/bar/lv_example_bar_3.c | 9 ++++++++- examples/widgets/bar/lv_example_bar_4.c | 9 ++++++++- examples/widgets/bar/lv_example_bar_5.c | 8 +++++++- examples/widgets/bar/lv_example_bar_6.c | 11 ++++++++++- examples/widgets/bar/lv_example_bar_7.c | 8 +++++++- examples/widgets/button/about.md | 4 ++++ examples/widgets/button/lv_example_button_2.c | 11 ++++++++++- examples/widgets/button/lv_example_button_3.c | 10 +++++++++- examples/widgets/buttonmatrix/about.md | 6 ++++++ .../buttonmatrix/lv_example_buttonmatrix_1.c | 13 +++++++++++++ .../buttonmatrix/lv_example_buttonmatrix_2.c | 11 ++++++++++- .../buttonmatrix/lv_example_buttonmatrix_3.c | 11 ++++++++++- examples/widgets/calendar/about.md | 4 ++++ .../widgets/calendar/lv_example_calendar_1.c | 13 +++++++++++++ .../widgets/calendar/lv_example_calendar_2.c | 13 +++++++++++++ examples/widgets/canvas/about.md | 4 ++++ examples/widgets/canvas/lv_example_canvas_1.c | 11 +++++++++++ .../widgets/canvas/lv_example_canvas_10.c | 10 +++++++++- .../widgets/canvas/lv_example_canvas_11.c | 11 +++++++++++ .../widgets/canvas/lv_example_canvas_12.c | 11 +++++++++++ examples/widgets/canvas/lv_example_canvas_2.c | 9 ++++++++- examples/widgets/canvas/lv_example_canvas_3.c | 9 ++++++++- examples/widgets/canvas/lv_example_canvas_4.c | 9 ++++++++- examples/widgets/canvas/lv_example_canvas_5.c | 9 ++++++++- examples/widgets/canvas/lv_example_canvas_6.c | 9 ++++++++- examples/widgets/canvas/lv_example_canvas_7.c | 8 +++++++- examples/widgets/canvas/lv_example_canvas_8.c | 12 +++++++++++- examples/widgets/canvas/lv_example_canvas_9.c | 9 ++++++++- examples/widgets/chart/about.md | 4 ++++ examples/widgets/chart/lv_example_chart_1.c | 10 +++++++++- examples/widgets/chart/lv_example_chart_2.c | 10 +++++++++- examples/widgets/chart/lv_example_chart_3.c | 11 ++++++++++- examples/widgets/chart/lv_example_chart_4.c | 9 ++++++++- examples/widgets/chart/lv_example_chart_5.c | 12 +++++++++++- examples/widgets/chart/lv_example_chart_6.c | 10 +++++++++- examples/widgets/chart/lv_example_chart_7.c | 12 +++++++++++- examples/widgets/chart/lv_example_chart_8.c | 9 ++++++++- examples/widgets/checkbox/about.md | 4 ++++ .../widgets/checkbox/lv_example_checkbox_1.c | 11 +++++++++++ .../widgets/checkbox/lv_example_checkbox_2.c | 11 ++++++++++- examples/widgets/dropdown/about.md | 4 ++++ .../widgets/dropdown/lv_example_dropdown_1.c | 9 +++++++++ .../widgets/dropdown/lv_example_dropdown_2.c | 10 +++++++++- .../widgets/dropdown/lv_example_dropdown_3.c | 11 ++++++++++- examples/widgets/image/about.md | 4 ++++ examples/widgets/image/lv_example_image_1.c | 10 ++++++++++ examples/widgets/image/lv_example_image_2.c | 10 +++++++++- examples/widgets/image/lv_example_image_3.c | 10 +++++++++- examples/widgets/image/lv_example_image_4.c | 10 +++++++++- examples/widgets/image/lv_example_image_5.c | 12 ++++++++++++ examples/widgets/imagebutton/about.md | 6 ++++++ .../imagebutton/lv_example_imagebutton_1.c | 13 +++++++++++++ examples/widgets/keyboard/about.md | 4 ++++ .../widgets/keyboard/lv_example_keyboard_1.c | 10 ++++++++++ .../widgets/keyboard/lv_example_keyboard_2.c | 10 ++++++++++ .../widgets/keyboard/lv_example_keyboard_3.c | 10 +++++++++- examples/widgets/label/about.md | 4 ++++ examples/widgets/label/lv_example_label_1.c | 9 ++++++++- examples/widgets/label/lv_example_label_2.c | 8 +++++++- examples/widgets/label/lv_example_label_3.c | 9 ++++++++- examples/widgets/label/lv_example_label_4.c | 9 ++++++++- examples/widgets/label/lv_example_label_5.c | 10 ++++++++-- examples/widgets/label/lv_example_label_6.c | 10 ++++++++++ examples/widgets/label/lv_example_label_7.c | 10 +++++++++- examples/widgets/led/about.md | 6 ++++++ examples/widgets/led/lv_example_led_1.c | 9 ++++++++- examples/widgets/line/about.md | 4 ++++ examples/widgets/line/lv_example_line_1.c | 10 ++++++++++ examples/widgets/list/about.md | 4 ++++ examples/widgets/list/lv_example_list_1.c | 11 +++++++++++ examples/widgets/list/lv_example_list_2.c | 13 +++++++++++++ examples/widgets/lottie/about.md | 4 ++++ examples/widgets/lottie/lv_example_lottie_1.c | 11 ++++++++++- examples/widgets/lottie/lv_example_lottie_2.c | 11 ++++++++++- examples/widgets/menu/about.md | 4 ++++ examples/widgets/menu/lv_example_menu_1.c | 11 +++++++++++ examples/widgets/menu/lv_example_menu_2.c | 13 +++++++++++++ examples/widgets/menu/lv_example_menu_3.c | 10 ++++++++++ examples/widgets/menu/lv_example_menu_4.c | 13 +++++++++++++ examples/widgets/menu/lv_example_menu_5.c | 15 +++++++++++++++ examples/widgets/msgbox/about.md | 6 ++++++ examples/widgets/msgbox/lv_example_msgbox_1.c | 12 ++++++++++++ examples/widgets/msgbox/lv_example_msgbox_2.c | 13 +++++++++++++ examples/widgets/msgbox/lv_example_msgbox_3.c | 12 ++++++++++++ examples/widgets/obj/about.md | 6 ++++++ examples/widgets/obj/lv_example_obj_1.c | 10 ++++++++++ examples/widgets/obj/lv_example_obj_2.c | 9 ++++++++- examples/widgets/obj/lv_example_obj_3.c | 11 +++++++++++ examples/widgets/roller/about.md | 6 ++++++ examples/widgets/roller/lv_example_roller_1.c | 9 ++++++++- examples/widgets/roller/lv_example_roller_2.c | 11 ++++++++++- examples/widgets/roller/lv_example_roller_3.c | 11 ++++++++++- examples/widgets/scale/about.md | 6 ++++++ examples/widgets/scale/lv_example_scale_1.c | 8 +++++++- examples/widgets/scale/lv_example_scale_10.c | 14 ++++++++++++++ examples/widgets/scale/lv_example_scale_11.c | 15 +++++++++++++++ examples/widgets/scale/lv_example_scale_12.c | 13 ++++++++++++- examples/widgets/scale/lv_example_scale_2.c | 11 ++++++++++- examples/widgets/scale/lv_example_scale_3.c | 11 ++++++++++- examples/widgets/scale/lv_example_scale_4.c | 10 +++++++++- examples/widgets/scale/lv_example_scale_5.c | 11 ++++++++++- examples/widgets/scale/lv_example_scale_6.c | 12 +++++++++++- examples/widgets/scale/lv_example_scale_7.c | 11 ++++++++++- examples/widgets/scale/lv_example_scale_8.c | 12 +++++++++++- examples/widgets/scale/lv_example_scale_9.c | 9 ++++++++- examples/widgets/slider/about.md | 4 ++++ examples/widgets/slider/lv_example_slider_1.c | 9 ++++++++- examples/widgets/slider/lv_example_slider_2.c | 11 ++++++++++- examples/widgets/slider/lv_example_slider_3.c | 9 ++++++++- examples/widgets/slider/lv_example_slider_4.c | 9 ++++++++- examples/widgets/span/about.md | 6 ++++++ examples/widgets/span/lv_example_span_1.c | 10 +++++++++- examples/widgets/spinbox/about.md | 6 ++++++ .../widgets/spinbox/lv_example_spinbox_1.c | 11 +++++++++++ examples/widgets/spinner/about.md | 4 ++++ .../widgets/spinner/lv_example_spinner_1.c | 8 ++++++++ examples/widgets/switch/about.md | 4 ++++ examples/widgets/switch/lv_example_switch_1.c | 11 +++++++++++ examples/widgets/switch/lv_example_switch_2.c | 11 +++++++++++ examples/widgets/table/about.md | 4 ++++ examples/widgets/table/lv_example_table_1.c | 13 +++++++++++++ examples/widgets/table/lv_example_table_2.c | 12 +++++++++++- examples/widgets/tabview/about.md | 4 ++++ .../widgets/tabview/lv_example_tabview_1.c | 11 +++++++++++ .../widgets/tabview/lv_example_tabview_2.c | 14 +++++++++++++- examples/widgets/textarea/about.md | 4 ++++ .../widgets/textarea/lv_example_textarea_1.c | 11 +++++++++++ .../widgets/textarea/lv_example_textarea_2.c | 10 ++++++++++ .../widgets/textarea/lv_example_textarea_3.c | 11 +++++++++-- .../widgets/textarea/lv_example_textarea_4.c | 11 +++++++++++ examples/widgets/tileview/about.md | 6 ++++++ .../widgets/tileview/lv_example_tileview_1.c | 13 ++++++++++--- examples/widgets/win/about.md | 6 ++++++ examples/widgets/win/lv_example_win_1.c | 12 ++++++++++++ 301 files changed, 2578 insertions(+), 191 deletions(-) create mode 100644 examples/about.md create mode 100644 examples/anim/about.md create mode 100644 examples/event/about.md create mode 100644 examples/get_started/about.md create mode 100644 examples/grad/about.md create mode 100644 examples/layouts/about.md create mode 100644 examples/layouts/flex/about.md create mode 100644 examples/layouts/grid/about.md create mode 100644 examples/libs/about.md create mode 100644 examples/libs/barcode/about.md create mode 100644 examples/libs/bmp/about.md create mode 100644 examples/libs/ffmpeg/about.md create mode 100644 examples/libs/freetype/about.md create mode 100644 examples/libs/gif/about.md create mode 100644 examples/libs/gltf/about.md create mode 100644 examples/libs/gstreamer/about.md create mode 100644 examples/libs/libjpeg_turbo/about.md create mode 100644 examples/libs/libpng/about.md create mode 100644 examples/libs/libwebp/about.md create mode 100644 examples/libs/lodepng/about.md create mode 100644 examples/libs/qrcode/about.md create mode 100644 examples/libs/rlottie/about.md create mode 100644 examples/libs/svg/about.md create mode 100644 examples/libs/tiny_ttf/about.md create mode 100644 examples/libs/tjpgd/about.md create mode 100644 examples/others/about.md create mode 100644 examples/others/file_explorer/about.md create mode 100644 examples/others/font_manager/about.md create mode 100644 examples/others/fragment/about.md create mode 100644 examples/others/gestures/about.md create mode 100644 examples/others/gridnav/about.md create mode 100644 examples/others/ime/about.md create mode 100644 examples/others/imgfont/about.md create mode 100644 examples/others/monkey/about.md create mode 100644 examples/others/observer/about.md create mode 100644 examples/others/snapshot/about.md create mode 100644 examples/others/translation/about.md create mode 100644 examples/porting/about.md create mode 100644 examples/porting/osal/about.md create mode 100644 examples/scroll/about.md create mode 100644 examples/styles/about.md create mode 100644 examples/widgets/about.md create mode 100644 examples/widgets/animimg/about.md create mode 100644 examples/widgets/arc/about.md create mode 100644 examples/widgets/arclabel/about.md create mode 100644 examples/widgets/bar/about.md create mode 100644 examples/widgets/button/about.md create mode 100644 examples/widgets/buttonmatrix/about.md create mode 100644 examples/widgets/calendar/about.md create mode 100644 examples/widgets/canvas/about.md create mode 100644 examples/widgets/chart/about.md create mode 100644 examples/widgets/checkbox/about.md create mode 100644 examples/widgets/dropdown/about.md create mode 100644 examples/widgets/image/about.md create mode 100644 examples/widgets/imagebutton/about.md create mode 100644 examples/widgets/keyboard/about.md create mode 100644 examples/widgets/label/about.md create mode 100644 examples/widgets/led/about.md create mode 100644 examples/widgets/line/about.md create mode 100644 examples/widgets/list/about.md create mode 100644 examples/widgets/lottie/about.md create mode 100644 examples/widgets/menu/about.md create mode 100644 examples/widgets/msgbox/about.md create mode 100644 examples/widgets/obj/about.md create mode 100644 examples/widgets/roller/about.md create mode 100644 examples/widgets/scale/about.md create mode 100644 examples/widgets/slider/about.md create mode 100644 examples/widgets/span/about.md create mode 100644 examples/widgets/spinbox/about.md create mode 100644 examples/widgets/spinner/about.md create mode 100644 examples/widgets/switch/about.md create mode 100644 examples/widgets/table/about.md create mode 100644 examples/widgets/tabview/about.md create mode 100644 examples/widgets/textarea/about.md create mode 100644 examples/widgets/tileview/about.md create mode 100644 examples/widgets/win/about.md diff --git a/examples/about.md b/examples/about.md new file mode 100644 index 0000000000..d922041d36 --- /dev/null +++ b/examples/about.md @@ -0,0 +1,6 @@ +--- +title: "Examples" +description: "Working LVGL examples. Compile, adapt, learn." +--- + +This section collects runnable LVGL examples organized by topic. Each page shows a focused snippet you can copy into a project, compile, and modify. Use the sidebar to jump between categories, starting with Getting Started if you are new to the library. diff --git a/examples/anim/about.md b/examples/anim/about.md new file mode 100644 index 0000000000..584fc54452 --- /dev/null +++ b/examples/anim/about.md @@ -0,0 +1,7 @@ +--- +title: "Animations" +description: "Animate widget properties over time with lv_anim." +order: 40 +--- + +An `lv_anim_t` describes a value interpolated between a start and end over a duration, with an optional easing path and completion callback. Animations tick on display refresh, so their smoothness tracks the refresh rate. You can chain animations, run them in parallel, and reuse a single `lv_anim_t` descriptor to drive any numeric property through a setter. diff --git a/examples/anim/lv_example_anim_2.c b/examples/anim/lv_example_anim_2.c index 24fe7bde6a..901a3a4db9 100644 --- a/examples/anim/lv_example_anim_2.c +++ b/examples/anim/lv_example_anim_2.c @@ -12,7 +12,15 @@ static void anim_size_cb(void * var, int32_t v) } /** - * Create a playback animation + * @title Infinite playback animation + * @brief Grow a red circle while sliding it right, then reverse and repeat. + * + * A red circular object sits on the left edge of the active screen. One + * `lv_anim_t` drives `lv_obj_set_size` from 10 to 50 over 1000 ms; the same + * configured animation is then reused with `lv_obj_set_x` running from 10 + * to 240. Both run with `lv_anim_path_ease_in_out`, a 300 ms reverse stage + * after a 100 ms reverse delay, a 500 ms gap between cycles, and + * `LV_ANIM_REPEAT_INFINITE`. */ void lv_example_anim_2(void) { diff --git a/examples/anim/lv_example_anim_3.c b/examples/anim/lv_example_anim_3.c index 31bd053912..0cff3f332e 100644 --- a/examples/anim/lv_example_anim_3.c +++ b/examples/anim/lv_example_anim_3.c @@ -1,13 +1,6 @@ #include "../lv_examples.h" #if LV_BUILD_EXAMPLES && LV_USE_SLIDER && LV_USE_CHART && LV_USE_BUTTON && LV_USE_GRID -/** - * the example show the use of cubic-bezier3 in animation. - * the control point P1,P2 of cubic-bezier3 can be adjusted by slider. - * and the chart shows the cubic-bezier3 in real time. you can click - * run button see animation in current point of cubic-bezier3. - */ - #define CHART_POINTS_NUM 256 struct { @@ -32,7 +25,17 @@ static void page_obj_init(lv_obj_t * par); static void anim_x_cb(void * var, int32_t v); /** - * create an animation + * @title Cubic-bezier animation editor + * @brief Edit a cubic-bezier path with two sliders while a chart plots it live. + * + * A 320x240 grid container holds an animated red square, two sliders that + * set the p1 and p2 control points of `lv_bezier3` (both ranged 0 to 1024), + * value labels, a play button with `LV_SYMBOL_PLAY`, and a scatter + * `lv_chart_t` that plots the current curve across 256 points. Slider + * `LV_EVENT_VALUE_CHANGED` callbacks update the stored control points and + * refresh the chart; clicking the play button calls `lv_anim_start` to run + * the square across the container using the custom bezier path callback + * over 2000 ms. */ void lv_example_anim_3(void) { diff --git a/examples/anim/lv_example_anim_4.c b/examples/anim/lv_example_anim_4.c index 1e92344887..0ec037e972 100644 --- a/examples/anim/lv_example_anim_4.c +++ b/examples/anim/lv_example_anim_4.c @@ -43,7 +43,15 @@ static void sw_event_cb(lv_event_t * e) } /** - * Start animation on an event + * @title Pause a running animation + * @brief Pause a label slide for one second shortly after it starts. + * + * A label and a pre-checked switch are placed on the active screen. When + * the switch's `LV_EVENT_VALUE_CHANGED` fires, an `lv_anim_t` slides the + * label to x=100 with `lv_anim_path_overshoot` on check or to `-width` + * with `lv_anim_path_ease_in` on uncheck, each 500 ms long. After starting + * the animation a 200 ms `lv_timer_t` calls `lv_anim_pause_for` to hold + * it for 1000 ms before it resumes. */ void lv_example_anim_4(void) { diff --git a/examples/anim/lv_example_anim_timeline_1.c b/examples/anim/lv_example_anim_timeline_1.c index 9ff2cf8363..b5cf985fa7 100644 --- a/examples/anim/lv_example_anim_timeline_1.c +++ b/examples/anim/lv_example_anim_timeline_1.c @@ -44,7 +44,18 @@ static void slider_prg_event_handler(lv_event_t * e) } /** - * Create an animation timeline + * @title Animation timeline with transport controls + * @brief Drive staggered grow animations through a timeline the user can pause or scrub. + * + * Three 90x70 objects are laid out in a flex row with a checkable Start + * button, a Pause button, and a progress slider ranged to + * `LV_ANIM_TIMELINE_PROGRESS_MAX`. An `lv_anim_timeline_t` schedules width + * and height animations for each object (`lv_anim_path_overshoot` for width + * and `lv_anim_path_ease_out` for height, each 300 ms) starting at offsets + * 0, 200, and 400 ms, plus a linear 700 ms animation that sweeps the + * slider. The Start button toggles forward and reverse playback via + * `lv_anim_timeline_set_reverse`, Pause calls `lv_anim_timeline_pause`, and + * dragging the slider calls `lv_anim_timeline_set_progress`. */ void lv_example_anim_timeline_1(void) { diff --git a/examples/event/about.md b/examples/event/about.md new file mode 100644 index 0000000000..83bf492f8a --- /dev/null +++ b/examples/event/about.md @@ -0,0 +1,7 @@ +--- +title: "Events" +description: "Widget events and user input handling." +order: 50 +--- + +Widgets emit events such as `LV_EVENT_CLICKED`, `LV_EVENT_VALUE_CHANGED`, `LV_EVENT_DRAW_MAIN`, and `LV_EVENT_KEY`. You register a callback with `lv_obj_add_event_cb()` and receive an `lv_event_t` pointer from which you read the code, target, and user data. The examples cover basic wiring, bubbling, custom event codes, and reading input device state inside a handler. diff --git a/examples/event/lv_example_event_bubble.c b/examples/event/lv_example_event_bubble.c index 1ef511e314..9543e9de4b 100644 --- a/examples/event/lv_example_event_bubble.c +++ b/examples/event/lv_example_event_bubble.c @@ -17,7 +17,14 @@ static void event_cb(lv_event_t * e) } /** - * Demonstrate event bubbling + * @title Event bubbling to a parent + * @brief Handle clicks on child buttons from a single container callback. + * + * A 290x200 container uses `LV_FLEX_FLOW_ROW_WRAP` and holds 30 small + * buttons, each flagged with `LV_OBJ_FLAG_EVENT_BUBBLE`. One + * `LV_EVENT_CLICKED` callback on the container reads + * `lv_event_get_target_obj` to identify which button was clicked and paints + * its background red; clicks on the container itself are ignored. */ void lv_example_event_bubble(void) { diff --git a/examples/event/lv_example_event_button.c b/examples/event/lv_example_event_button.c index afc9ce6ba5..222704e0f0 100644 --- a/examples/event/lv_example_event_button.c +++ b/examples/event/lv_example_event_button.c @@ -25,7 +25,14 @@ static void event_cb(lv_event_t * e) } /** - * Handle multiple events + * @title Handle multiple button events + * @brief Report the most recent button event on a second label. + * + * A centered button with a `Click me!` label is paired with an info label + * on the active screen. A single callback subscribed with `LV_EVENT_ALL` + * switches on `lv_event_get_code` and writes the name of the latest event + * (`LV_EVENT_PRESSED`, `LV_EVENT_CLICKED`, `LV_EVENT_LONG_PRESSED`, + * `LV_EVENT_LONG_PRESSED_REPEAT`) into the info label. */ void lv_example_event_button(void) { diff --git a/examples/event/lv_example_event_draw.c b/examples/event/lv_example_event_draw.c index da8191dda9..7f76297c54 100644 --- a/examples/event/lv_example_event_draw.c +++ b/examples/event/lv_example_event_draw.c @@ -45,7 +45,15 @@ static void event_cb(lv_event_t * e) } /** - * Demonstrate the usage of draw event + * @title Custom drawing on draw task events + * @brief Draw a pulsing red circle on top of a container with a draw task callback. + * + * A 200x200 container is centered and flagged with + * `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS`. An `LV_EVENT_DRAW_TASK_ADDED` + * callback inspects the draw task and, when `base_dsc->part` is + * `LV_PART_MAIN`, calls `lv_draw_rect` to paint a pink circle with a red + * border and outline. A 30 ms `lv_timer_t` bounces a `size` counter between + * 0 and 50 and invalidates the container each tick to animate the circle. */ void lv_example_event_draw(void) { diff --git a/examples/event/lv_example_event_streak.c b/examples/event/lv_example_event_streak.c index d9a61ef132..de0e51ba95 100644 --- a/examples/event/lv_example_event_streak.c +++ b/examples/event/lv_example_event_streak.c @@ -27,8 +27,6 @@ static void streak_event_cb(lv_event_t * e) * reads `lv_indev_get_short_click_streak()` and writes the count to a * separate label; `LV_EVENT_SINGLE_CLICKED`, `LV_EVENT_DOUBLE_CLICKED`, and * `LV_EVENT_TRIPLE_CLICKED` each set the button's label to a matching string. - * - * @hide_in_docs */ void lv_example_event_streak(void) { diff --git a/examples/event/lv_example_event_trickle.c b/examples/event/lv_example_event_trickle.c index 954f5d56c6..d1990bf71f 100644 --- a/examples/event/lv_example_event_trickle.c +++ b/examples/event/lv_example_event_trickle.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_FLEX /** - * Demonstrate event trickle + * @title Event trickle to children + * @brief Forward pressed state from a flex container down to its children. + * + * A 290x200 container with `LV_FLEX_FLOW_ROW_WRAP` holds nine small + * sub-containers, each with a numbered label. The container is flagged with + * `LV_OBJ_FLAG_EVENT_TRICKLE` so its input events reach the children; a + * single white-on-black style is added to the container for + * `LV_STATE_PRESSED` and to each sub-container for `LV_STATE_FOCUSED`, so + * pressing the container flips the whole group to the dark style. */ void lv_example_event_trickle(void) { diff --git a/examples/get_started/about.md b/examples/get_started/about.md new file mode 100644 index 0000000000..0cf672d560 --- /dev/null +++ b/examples/get_started/about.md @@ -0,0 +1,7 @@ +--- +title: "Getting Started" +description: "Your first LVGL programs." +order: 10 +--- + +These examples introduce the core workflow: creating a label, attaching a click callback to a button, applying styles, and reading a slider value through an event. Begin here if you have not written an LVGL program before. Once the patterns feel familiar, move on to Styles and Events for deeper coverage. diff --git a/examples/get_started/lv_example_get_started_2.c b/examples/get_started/lv_example_get_started_2.c index 247fc539c7..6b7ffc71e5 100644 --- a/examples/get_started/lv_example_get_started_2.c +++ b/examples/get_started/lv_example_get_started_2.c @@ -16,7 +16,13 @@ static void btn_event_cb(lv_event_t * e) } /** - * Create a button with a label and react on click event. + * @title Button with click counter + * @brief Increment a label on a button each time it is clicked. + * + * A button sized 120x50 is placed at position (10, 10) on the active screen + * with a centered label reading `Button`. The button subscribes to + * `LV_EVENT_ALL` and on `LV_EVENT_CLICKED` the callback updates its child + * label with `lv_label_set_text_fmt` to show an incrementing counter. */ void lv_example_get_started_2(void) { diff --git a/examples/get_started/lv_example_get_started_3.c b/examples/get_started/lv_example_get_started_3.c index b869cc6338..ab1505546f 100644 --- a/examples/get_started/lv_example_get_started_3.c +++ b/examples/get_started/lv_example_get_started_3.c @@ -42,7 +42,16 @@ static void style_init(void) } /** - * Create styles from scratch for buttons. + * @title Styles from scratch for buttons + * @brief Build reusable button styles and apply them with a pressed-state override. + * + * Three `lv_style_t` objects are initialized: a base grey gradient style with + * rounded corners and a thin border, a pressed style that applies a darken + * color filter at `LV_OPA_20`, and a red style that overrides only the + * background colors. Two buttons strip their theme styles with + * `lv_obj_remove_style_all`, adopt the base style for the default state and + * the pressed style for `LV_STATE_PRESSED`; the second also stacks the red + * style and sets a local `LV_RADIUS_CIRCLE` radius. */ void lv_example_get_started_3(void) { diff --git a/examples/get_started/lv_example_get_started_4.c b/examples/get_started/lv_example_get_started_4.c index 368473c3ed..38c42c88d9 100644 --- a/examples/get_started/lv_example_get_started_4.c +++ b/examples/get_started/lv_example_get_started_4.c @@ -13,7 +13,13 @@ static void slider_event_cb(lv_event_t * e) } /** - * Create a slider and write its value on a label. + * @title Slider with live value label + * @brief Mirror a slider's value into a label anchored above it. + * + * A 200 px wide slider is centered on the active screen with a label placed + * 15 px above it via `lv_obj_align_to` and `LV_ALIGN_OUT_TOP_MID`. An + * `LV_EVENT_VALUE_CHANGED` callback reads `lv_slider_get_value` and rewrites + * the label text, re-aligning it after each update. */ void lv_example_get_started_4(void) { diff --git a/examples/grad/about.md b/examples/grad/about.md new file mode 100644 index 0000000000..a9f7a73e91 --- /dev/null +++ b/examples/grad/about.md @@ -0,0 +1,7 @@ +--- +title: "Gradients" +description: "Linear, radial, and conic gradient fills." +order: 30 +--- + +LVGL supports linear, radial, and conic gradients as background fills. Each type accepts color stops and geometric parameters (direction, center, radius) and can be applied through the style system wherever a background color is valid. The examples here show each gradient flavor on typical widgets. diff --git a/examples/grad/lv_example_grad_1.c b/examples/grad/lv_example_grad_1.c index 3fd25fc868..dc8786ce16 100644 --- a/examples/grad/lv_example_grad_1.c +++ b/examples/grad/lv_example_grad_1.c @@ -60,8 +60,17 @@ static void frac_2_event_cb(lv_event_t * e) } /** - * Play with a simple horizontal gradient. - * Adjust the stop positions of the gradient. + * @title Horizontal gradient with draggable stops + * @brief Drag two bullets to move the stop fractions of a red-to-green horizontal gradient. + * + * A centered 80% by 80% object carries a two-stop horizontal gradient + * (red at 20%, transparent green at 80%) built with `lv_grad_init_stops` + * and `lv_grad_horizontal_init` and applied through + * `lv_style_set_bg_grad`. Two small buttons sitting on top act as handles; + * their `LV_EVENT_PRESSING` callbacks read the pointer with + * `lv_indev_get_point`, reposition the handle, and write the resulting + * x fraction into `dsc->stops[0].frac` or `dsc->stops[1].frac` before + * invalidating the parent. */ void lv_example_grad_1(void) { diff --git a/examples/grad/lv_example_grad_2.c b/examples/grad/lv_example_grad_2.c index e59600c108..27871f5eb8 100644 --- a/examples/grad/lv_example_grad_2.c +++ b/examples/grad/lv_example_grad_2.c @@ -54,8 +54,19 @@ static void end_event_cb(lv_event_t * e) } /** - * Play with the linear gradient. - * Adjust the 2 point in between the a linear gradient can be drawn (can be skew as well) + * @title Linear gradient with draggable endpoints + * @brief Drag two bullets to reposition the start and end points of a skewable linear gradient. + * + * A centered 80% by 80% object carries a two-stop linear gradient + * (red at the start, transparent green at the end) built with + * `lv_grad_init_stops` and `lv_grad_linear_init` from (100, 100) to + * (200, 150) using `LV_GRAD_EXTEND_PAD`. Two small buttons mark the + * endpoints; their `LV_EVENT_PRESSING` callbacks read the pointer with + * `lv_indev_get_point`, reposition the handle, and write + * `dsc->params.linear.start` or `dsc->params.linear.end` before + * invalidating the parent. When `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is + * disabled, the example instead shows a single label noting the + * dependency. */ void lv_example_grad_2(void) { diff --git a/examples/grad/lv_example_grad_3.c b/examples/grad/lv_example_grad_3.c index cc9368aca5..455b8ffe6c 100644 --- a/examples/grad/lv_example_grad_3.c +++ b/examples/grad/lv_example_grad_3.c @@ -59,9 +59,19 @@ static void end_event_cb(lv_event_t * e) } /** - * Play with the radial gradient - * Adjust the end circle and focal point position. - * The radius of the end circle and an focal point are hardcoded in the example. + * @title Radial gradient with draggable centers + * @brief Drag two bullets to move the focal point and the end circle of a radial gradient. + * + * A centered 80% by 80% object carries a two-stop radial gradient built + * with `lv_grad_init_stops`, `lv_grad_radial_init` (end circle centered at + * 100, 100 with edge at 200, 100), and `lv_grad_radial_set_focal` at + * (50, 50). Two small buttons mark the focal point and the end circle + * center; their `LV_EVENT_PRESSING` callbacks read the pointer and write + * `dsc->params.radial.focal` (with `focal_extent` offset by 10) or + * `dsc->params.radial.end` (with `end_extent` offset by 100) before + * invalidating the parent. When `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is + * disabled, the example instead shows a single label noting the + * dependency. */ void lv_example_grad_3(void) { diff --git a/examples/grad/lv_example_grad_4.c b/examples/grad/lv_example_grad_4.c index 07fddc45a1..cf67f4af97 100644 --- a/examples/grad/lv_example_grad_4.c +++ b/examples/grad/lv_example_grad_4.c @@ -58,7 +58,18 @@ static void end_event_cb(lv_event_t * e) } /** - * Play with the conical gradient + * @title Conical gradient with draggable angles + * @brief Drag two bullets to set the start and end angles of a conical gradient. + * + * A centered 80% by 80% object carries a two-stop conical gradient built + * with `lv_grad_init_stops` and `lv_grad_conical_init` centered at 50% by + * 50% sweeping from 0 to 180 degrees with `LV_GRAD_EXTEND_PAD`. Two small + * buttons act as angle handles; their `LV_EVENT_PRESSING` callbacks read + * the pointer, reposition the handle, and recompute + * `dsc->params.conical.start_angle` or `dsc->params.conical.end_angle` + * with `lv_atan2` relative to the parent center before invalidating it. + * When `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is disabled, the example + * instead shows a single label noting the dependency. */ void lv_example_grad_4(void) { diff --git a/examples/layouts/about.md b/examples/layouts/about.md new file mode 100644 index 0000000000..db2ba43be5 --- /dev/null +++ b/examples/layouts/about.md @@ -0,0 +1,7 @@ +--- +title: "Layouts" +description: "Automatic positioning with Flex and Grid." +order: 60 +--- + +LVGL ships two automatic layout engines. Flex arranges children along a single axis (row or column), similar to CSS Flexbox, and is the fastest way to stack or space items. Grid places children into rows and columns of configurable size, comparable to CSS Grid, and suits dashboards or form-like screens where content aligns in both dimensions. Reach for Flex when one axis is enough; switch to Grid when cells need to line up across rows and columns. diff --git a/examples/layouts/flex/about.md b/examples/layouts/flex/about.md new file mode 100644 index 0000000000..2d1d4adbf7 --- /dev/null +++ b/examples/layouts/flex/about.md @@ -0,0 +1,6 @@ +--- +title: "Flex" +order: 5 +--- + +A 1D layout that arranges children in a row or column, analogous to CSS Flexbox. Useful for toolbars, lists, and any stack where one axis drives placement. diff --git a/examples/layouts/flex/lv_example_flex_2.c b/examples/layouts/flex/lv_example_flex_2.c index 25a4ce0d35..70cbb85c53 100644 --- a/examples/layouts/flex/lv_example_flex_2.c +++ b/examples/layouts/flex/lv_example_flex_2.c @@ -2,7 +2,14 @@ #if LV_USE_FLEX && LV_BUILD_EXAMPLES /** - * Arrange items in rows with wrap and place the items to get even space around them. + * @title Row wrap with even spacing + * @brief A 300x220 container lays out eight checkable tiles in wrapping rows with even spacing. + * + * A reusable `lv_style_t` sets `LV_LAYOUT_FLEX`, `LV_FLEX_FLOW_ROW_WRAP`, and + * `LV_FLEX_ALIGN_SPACE_EVENLY` on the main axis. The style is applied to a + * centered container holding eight 70 px-wide tiles with `LV_SIZE_CONTENT` + * height. Each tile carries `LV_OBJ_FLAG_CHECKABLE` so it toggles between + * default and `LV_STATE_CHECKED` when clicked. */ void lv_example_flex_2(void) { diff --git a/examples/layouts/flex/lv_example_flex_3.c b/examples/layouts/flex/lv_example_flex_3.c index 207e6b9de3..15666c15f3 100644 --- a/examples/layouts/flex/lv_example_flex_3.c +++ b/examples/layouts/flex/lv_example_flex_3.c @@ -2,7 +2,14 @@ #if LV_USE_FLEX && LV_BUILD_EXAMPLES /** - * Demonstrate flex grow. + * @title Flex grow between fixed items + * @brief Distribute leftover row space between two grow items bracketed by fixed-size items. + * + * A 300x220 row container holds four children. The first and last are fixed + * 40x40 squares. The two middle children have a fixed height of 40 and take + * `lv_obj_set_flex_grow` weights of 1 and 2, splitting the remaining + * horizontal space in that proportion while the trailing fixed item is pushed + * against the right edge. */ void lv_example_flex_3(void) { diff --git a/examples/layouts/flex/lv_example_flex_4.c b/examples/layouts/flex/lv_example_flex_4.c index 12d4404bd8..495ebe4465 100644 --- a/examples/layouts/flex/lv_example_flex_4.c +++ b/examples/layouts/flex/lv_example_flex_4.c @@ -2,7 +2,13 @@ #if LV_USE_FLEX && LV_BUILD_EXAMPLES /** - * Reverse the order of flex items + * @title Reversed column flex order + * @brief Stack six items bottom-up inside a centered container. + * + * A 300x220 container uses `LV_FLEX_FLOW_COLUMN_REVERSE`, so items added later + * in the loop appear higher on screen. Six 100x50 children numbered 0 through + * 5 are added in ascending order but rendered in reverse, with "Item: 0" + * sitting at the bottom of the container. */ void lv_example_flex_4(void) { diff --git a/examples/layouts/flex/lv_example_flex_5.c b/examples/layouts/flex/lv_example_flex_5.c index 586503269e..5f1321318b 100644 --- a/examples/layouts/flex/lv_example_flex_5.c +++ b/examples/layouts/flex/lv_example_flex_5.c @@ -12,7 +12,14 @@ static void column_gap_anim(void * obj, int32_t v) } /** - * Demonstrate the effect of column and row gap style properties + * @title Animated row and column gaps + * @brief Drive row and column padding of a wrap container with two looping animations. + * + * A 300x220 container uses `LV_FLEX_FLOW_ROW_WRAP` to arrange nine 70 px + * tiles. Two `lv_anim_t` instances animate `pad_row` and `pad_column` + * between 0 and 10 with `LV_ANIM_REPEAT_INFINITE`: the row gap cycles every + * 500 ms in each direction while the column gap cycles every 3000 ms, so the + * tile spacing shifts on two independent time scales. */ void lv_example_flex_5(void) { diff --git a/examples/layouts/flex/lv_example_flex_6.c b/examples/layouts/flex/lv_example_flex_6.c index b08cc33db3..f68ad91cd1 100644 --- a/examples/layouts/flex/lv_example_flex_6.c +++ b/examples/layouts/flex/lv_example_flex_6.c @@ -2,8 +2,14 @@ #if LV_USE_FLEX && LV_BUILD_EXAMPLES /** - * RTL base direction changes order of the items. - * Also demonstrate how horizontal scrolling works with RTL. + * @title RTL flex wrap and scrolling + * @brief Lay out twenty tiles in a right-to-left wrapping flex container. + * + * A 300x220 container has `LV_BASE_DIR_RTL` set on its main part, then + * switches to `LV_FLEX_FLOW_ROW_WRAP`. Twenty 70 px tiles are placed in + * ascending order; the RTL base direction flips the main axis so item 0 sits + * at the top-right and rows fill leftward, and horizontal scrolling follows + * the same reversed direction. */ void lv_example_flex_6(void) { diff --git a/examples/layouts/grid/about.md b/examples/layouts/grid/about.md new file mode 100644 index 0000000000..c35ba6f4d6 --- /dev/null +++ b/examples/layouts/grid/about.md @@ -0,0 +1,6 @@ +--- +title: "Grid" +order: 10 +--- + +A 2D cell-based layout that places children into explicit rows and columns, analogous to CSS Grid. Use it when content must align across both axes, such as dashboards or forms. diff --git a/examples/layouts/grid/lv_example_grid_1.c b/examples/layouts/grid/lv_example_grid_1.c index 6ffdc6e9a6..e431fbf25f 100644 --- a/examples/layouts/grid/lv_example_grid_1.c +++ b/examples/layouts/grid/lv_example_grid_1.c @@ -2,7 +2,14 @@ #if LV_USE_GRID && LV_BUILD_EXAMPLES /** - * A simple grid + * @title Fixed-pixel 3x3 grid + * @brief Fill a 3x3 grid of fixed-size cells with stretched buttons. + * + * A 300x220 container is given three 70 px columns and three 50 px rows via + * `lv_obj_set_style_grid_column_dsc_array` and + * `lv_obj_set_style_grid_row_dsc_array`, then switched to `LV_LAYOUT_GRID`. + * Nine buttons are placed one per cell with `LV_GRID_ALIGN_STRETCH` on both + * axes so each button fills its cell and carries a `cX, rY` label. */ void lv_example_grid_1(void) { diff --git a/examples/layouts/grid/lv_example_grid_2.c b/examples/layouts/grid/lv_example_grid_2.c index 92e33b0084..31816345a3 100644 --- a/examples/layouts/grid/lv_example_grid_2.c +++ b/examples/layouts/grid/lv_example_grid_2.c @@ -2,7 +2,14 @@ #if LV_USE_GRID && LV_BUILD_EXAMPLES /** - * Demonstrate cell placement and span + * @title Cell alignment and spans + * @brief Mix per-cell alignments with two-cell spans inside a 3x3 grid. + * + * A 300x220 container uses three 70 px columns and three 50 px rows. Five + * `LV_SIZE_CONTENT` children are placed via `lv_obj_set_grid_cell`: the top + * row mixes `LV_GRID_ALIGN_START`, `LV_GRID_ALIGN_CENTER`, and + * `LV_GRID_ALIGN_END` alignments, a child at column 1 spans two columns with + * `LV_GRID_ALIGN_STRETCH`, and a child at row 1 spans two rows the same way. */ void lv_example_grid_2(void) { diff --git a/examples/layouts/grid/lv_example_grid_4.c b/examples/layouts/grid/lv_example_grid_4.c index 8d10eb02a3..a16556f5f0 100644 --- a/examples/layouts/grid/lv_example_grid_4.c +++ b/examples/layouts/grid/lv_example_grid_4.c @@ -2,7 +2,14 @@ #if LV_USE_GRID && LV_BUILD_EXAMPLES /** - * Demonstrate track placement + * @title Track placement in extra space + * @brief Place nine grid cells with space-between columns and bottom-aligned rows. + * + * A 300x220 container defines three 60 px columns and three 45 px rows that + * do not fill the full size. `lv_obj_set_grid_align` is called with + * `LV_GRID_ALIGN_SPACE_BETWEEN` for columns and `LV_GRID_ALIGN_END` for rows, + * so leftover horizontal space is distributed between the three columns and + * the rows collapse against the bottom of the container. */ void lv_example_grid_4(void) { diff --git a/examples/layouts/grid/lv_example_grid_5.c b/examples/layouts/grid/lv_example_grid_5.c index 6299269ee2..931b205119 100644 --- a/examples/layouts/grid/lv_example_grid_5.c +++ b/examples/layouts/grid/lv_example_grid_5.c @@ -12,7 +12,14 @@ static void column_gap_anim(void * obj, int32_t v) } /** - * Demonstrate column and row gap + * @title Animated grid row and column gaps + * @brief Animate `pad_row` and `pad_column` of a 3x3 grid on two timescales. + * + * A 300x220 container uses three 60 px columns and three 45 px rows, with + * nine stretched children labeled by cell coordinates. Two `lv_anim_t` + * instances loop `pad_row` and `pad_column` between 0 and 10 with + * `LV_ANIM_REPEAT_INFINITE`: row gap takes 500 ms per direction while column + * gap takes 3000 ms, so the grid breathes on two independent cycles. */ void lv_example_grid_5(void) { diff --git a/examples/layouts/grid/lv_example_grid_6.c b/examples/layouts/grid/lv_example_grid_6.c index 3df07b906c..1b0f285cbe 100644 --- a/examples/layouts/grid/lv_example_grid_6.c +++ b/examples/layouts/grid/lv_example_grid_6.c @@ -2,7 +2,14 @@ #if LV_USE_GRID && LV_BUILD_EXAMPLES /** - * Demonstrate RTL direction on grid + * @title RTL grid column order + * @brief Populate a 3x3 grid under right-to-left base direction. + * + * A 300x220 container has `LV_BASE_DIR_RTL` applied before its column and + * row descriptors (three 60 px and three 45 px tracks). Nine stretched + * children are placed into columns 0, 1, 2 in loop order, but the RTL base + * direction maps column 0 to the rightmost track, so the cells read + * right-to-left. */ void lv_example_grid_6(void) { diff --git a/examples/libs/about.md b/examples/libs/about.md new file mode 100644 index 0000000000..dc3fbe9cd5 --- /dev/null +++ b/examples/libs/about.md @@ -0,0 +1,7 @@ +--- +title: "3rd-Party Libraries" +description: "Integrations with image, font, video, and graphics libraries." +order: 90 +--- + +LVGL decodes a range of image, font, and video formats when the matching library is enabled in `lv_conf.h` (for example PNG, JPG, GIF, BMP, FreeType, and FFmpeg). Each integration has its own page covering how to enable it, expected dependencies, and a usage example. Pick the libraries you need and leave the rest disabled to keep the build small. diff --git a/examples/libs/barcode/about.md b/examples/libs/barcode/about.md new file mode 100644 index 0000000000..42a66afe54 --- /dev/null +++ b/examples/libs/barcode/about.md @@ -0,0 +1,6 @@ +--- +title: "Barcode" +order: 80 +--- + +Generates 1D barcodes as LVGL canvas images using code128. Enable with `LV_USE_BARCODE` in `lv_conf.h`. diff --git a/examples/libs/barcode/lv_example_barcode_1.c b/examples/libs/barcode/lv_example_barcode_1.c index eea012ce62..cf61a1bfc0 100644 --- a/examples/libs/barcode/lv_example_barcode_1.c +++ b/examples/libs/barcode/lv_example_barcode_1.c @@ -2,7 +2,14 @@ #if LV_USE_BARCODE && LV_BUILD_EXAMPLES /** - * Create a Barcode + * @title Barcode with palette colors + * @brief Render a barcode encoding an LVGL URL with custom dark and light colors. + * + * A barcode widget is centered on the active screen with its height set to 50 px. + * `lv_barcode_set_dark_color` and `lv_barcode_set_light_color` use darkened and + * lightened entries from `LV_PALETTE_BLUE` and `LV_PALETTE_LIGHT_BLUE` for the + * bars and background, a matching border color is applied, and + * `lv_barcode_update` encodes `https://lvgl.io`. */ void lv_example_barcode_1(void) { diff --git a/examples/libs/bmp/about.md b/examples/libs/bmp/about.md new file mode 100644 index 0000000000..c884f9c18b --- /dev/null +++ b/examples/libs/bmp/about.md @@ -0,0 +1,6 @@ +--- +title: "BMP" +order: 25 +--- + +BMP image decoder integration. Enable with `LV_USE_BMP` in `lv_conf.h`. diff --git a/examples/libs/bmp/lv_example_bmp_1.c b/examples/libs/bmp/lv_example_bmp_1.c index 2dc8713acb..a5c60f15c2 100644 --- a/examples/libs/bmp/lv_example_bmp_1.c +++ b/examples/libs/bmp/lv_example_bmp_1.c @@ -2,7 +2,13 @@ #if LV_USE_BMP && LV_BUILD_EXAMPLES /** - * Open a BMP file from a file + * @title Decode BMP from filesystem + * @brief Load a 32-bit BMP file through the LVGL filesystem and center it on the screen. + * + * An image widget is created on the active screen and its source is set to + * `A:lvgl/examples/libs/bmp/example_32bit.bmp` so the BMP decoder reads the + * file through an attached filesystem driver registered under drive letter + * `A`, such as `LV_USE_FS_STDIO`. */ void lv_example_bmp_1(void) { diff --git a/examples/libs/ffmpeg/about.md b/examples/libs/ffmpeg/about.md new file mode 100644 index 0000000000..c74377277b --- /dev/null +++ b/examples/libs/ffmpeg/about.md @@ -0,0 +1,6 @@ +--- +title: "FFmpeg" +order: 60 +--- + +Decodes video streams and a wide range of image formats via FFmpeg. Enable with `LV_USE_FFMPEG` in `lv_conf.h`. diff --git a/examples/libs/ffmpeg/lv_example_ffmpeg_1.c b/examples/libs/ffmpeg/lv_example_ffmpeg_1.c index 4a75cf49e5..2dfd42dc4d 100644 --- a/examples/libs/ffmpeg/lv_example_ffmpeg_1.c +++ b/examples/libs/ffmpeg/lv_example_ffmpeg_1.c @@ -3,7 +3,14 @@ #if LV_USE_FFMPEG && LV_FFMPEG_PLAYER_USE_LV_FS /** - * Open an image from a file + * @title Decode image with FFmpeg + * @brief Open a PNG through the FFmpeg integration and center it on the screen. + * + * An image widget is created on the active screen and its source is set to + * `A:lvgl/examples/libs/ffmpeg/ffmpeg.png`. The FFmpeg image path always + * routes through the LVGL filesystem abstraction regardless of + * `LV_FFMPEG_PLAYER_USE_LV_FS`, so the file is read via the driver registered + * under drive letter `A`. */ void lv_example_ffmpeg_1(void) { diff --git a/examples/libs/ffmpeg/lv_example_ffmpeg_2.c b/examples/libs/ffmpeg/lv_example_ffmpeg_2.c index bd1dfddcc3..abbb159d6a 100644 --- a/examples/libs/ffmpeg/lv_example_ffmpeg_2.c +++ b/examples/libs/ffmpeg/lv_example_ffmpeg_2.c @@ -9,7 +9,14 @@ #endif /** - * Open a video from a file + * @title Play MP4 video with FFmpeg + * @brief Play an MP4 clip on loop through the FFmpeg player widget. + * + * An `lv_ffmpeg_player` is centered on the active screen and pointed at + * `birds.mp4`. The decoder is requested as `h264_v4l2m2m` (with software + * fallback when V4L2 is unavailable), auto-restart is enabled, and + * `LV_FFMPEG_PLAYER_CMD_START` begins playback. The source path uses an + * `A:` prefix when `LV_FFMPEG_PLAYER_USE_LV_FS` is set, otherwise `./`. */ void lv_example_ffmpeg_2(void) { diff --git a/examples/libs/freetype/about.md b/examples/libs/freetype/about.md new file mode 100644 index 0000000000..1296f5c557 --- /dev/null +++ b/examples/libs/freetype/about.md @@ -0,0 +1,6 @@ +--- +title: "FreeType" +order: 30 +--- + +Rasterizes TrueType and OpenType fonts at runtime for LVGL text rendering. Enable with `LV_USE_FREETYPE` in `lv_conf.h`. diff --git a/examples/libs/freetype/lv_example_freetype_1.c b/examples/libs/freetype/lv_example_freetype_1.c index 5aba4c4fe2..d69ccd9d3a 100644 --- a/examples/libs/freetype/lv_example_freetype_1.c +++ b/examples/libs/freetype/lv_example_freetype_1.c @@ -9,7 +9,15 @@ #endif /** - * Load a font with FreeType + * @title FreeType bitmap font + * @brief Render a label with a 24 px bitmap TTF loaded via FreeType. + * + * `lv_freetype_font_create` loads `Lato-Regular.ttf` in + * `LV_FREETYPE_FONT_RENDER_MODE_BITMAP` at 24 px with + * `LV_FREETYPE_FONT_STYLE_NORMAL`. A style binds the font and centers text, + * then a label carrying a two-line greeting is placed at the center of the + * active screen. The path prefix resolves to `A:` when + * `LV_FREETYPE_USE_LVGL_PORT` is enabled and `./` otherwise. */ void lv_example_freetype_1(void) { diff --git a/examples/libs/freetype/lv_example_freetype_2.c b/examples/libs/freetype/lv_example_freetype_2.c index 4a2fcaca0e..c83d80e767 100644 --- a/examples/libs/freetype/lv_example_freetype_2.c +++ b/examples/libs/freetype/lv_example_freetype_2.c @@ -50,7 +50,14 @@ void lv_example_freetype_2_vector_font(uint32_t font_size, uint32_t border_width } /** - * Load a font with FreeType + * @title FreeType emoji fallback font + * @brief Render a large label whose primary font falls back to a color emoji font. + * + * A 400 px bitmap `Lato-Regular.ttf` is loaded as the primary font and a + * 200 px subset of `NotoColorEmoji-32.subset.ttf` is loaded as + * `font->fallback`. A style applies the combined font and centers the text, + * and a label placed at the center of the active screen shows a greeting + * ending in an emoji so the fallback glyph is exercised. */ void lv_example_freetype_2(void) { diff --git a/examples/libs/freetype/lv_example_freetype_3.c b/examples/libs/freetype/lv_example_freetype_3.c index c292e85b56..92ca2e2c8e 100644 --- a/examples/libs/freetype/lv_example_freetype_3.c +++ b/examples/libs/freetype/lv_example_freetype_3.c @@ -31,7 +31,15 @@ static void create_label(lv_font_kerning_t kerning, int32_t y_ofs, const char * } /** - * FreeType kerning example + * @title FreeType kerning comparison + * @brief Compare a FreeType-loaded font rendered with and without kerning. + * + * A static helper builds a 32 px `Lato-Regular.ttf` font via + * `lv_freetype_font_create_with_info`, applies it to a label with + * `lv_obj_set_style_text_font`, and centers the label at a given y offset. + * The public function calls the helper twice, once with + * `LV_FONT_KERNING_NONE` above center and once with `LV_FONT_KERNING_NORMAL` + * below, both showing the pair test string `AVAWAY,ToTaTe`. */ void lv_example_freetype_3(void) { diff --git a/examples/libs/gif/about.md b/examples/libs/gif/about.md new file mode 100644 index 0000000000..c0ed9f6ea1 --- /dev/null +++ b/examples/libs/gif/about.md @@ -0,0 +1,6 @@ +--- +title: "GIF" +order: 75 +--- + +Animated GIF decoder for playing GIFs inside LVGL image widgets. Enable with `LV_USE_GIF` in `lv_conf.h`. diff --git a/examples/libs/gif/lv_example_gif_1.c b/examples/libs/gif/lv_example_gif_1.c index 23af6ff4cd..8fe3867485 100644 --- a/examples/libs/gif/lv_example_gif_1.c +++ b/examples/libs/gif/lv_example_gif_1.c @@ -2,7 +2,14 @@ #if LV_USE_GIF && LV_BUILD_EXAMPLES /** - * Open a GIF image from a file and a variable + * @title Animated GIF from array and file + * @brief Show the same bulb GIF decoded from a C array and from a file path. + * + * Two `lv_gif` widgets are created on the active screen with + * `LV_COLOR_FORMAT_ARGB8888`. The left one binds to the embedded + * `img_bulb_gif` descriptor via `lv_gif_set_src`; the right one reads + * `A:lvgl/examples/libs/gif/bulb.gif` through the filesystem driver + * registered under drive letter `A`. */ void lv_example_gif_1(void) { diff --git a/examples/libs/gltf/about.md b/examples/libs/gltf/about.md new file mode 100644 index 0000000000..9229fcd2a0 --- /dev/null +++ b/examples/libs/gltf/about.md @@ -0,0 +1,6 @@ +--- +title: "glTF" +order: 20 +--- + +Loads and renders 3D models in glTF format within LVGL. Enable with `LV_USE_GLTF` in `lv_conf.h`. diff --git a/examples/libs/gltf/lv_example_gltf_1.c b/examples/libs/gltf/lv_example_gltf_1.c index 6cfa84f0a9..637ef1476e 100644 --- a/examples/libs/gltf/lv_example_gltf_1.c +++ b/examples/libs/gltf/lv_example_gltf_1.c @@ -19,7 +19,15 @@ static void spin_timer_cb(lv_timer_t * timer) } /** - * Open a GLTF from a file and make it spin forever like a platter + * @title Spin a glTF model on a platter + * @brief Load a glTF scene and spin it around the yaw axis with a timer. + * + * `lv_gltf_create` attaches the viewer to the active screen and + * `lv_obj_set_size` sizes it to fill the screen. `lv_gltf_load_model_from_file` + * loads `webp_diffuse_transmission_plant.glb` from drive letter `A`. The first + * embedded animation plays, the viewer is pitched down by 45 degrees, and a + * timer running at `LV_DEF_REFR_PERIOD` advances yaw by one degree per tick, + * wrapping at 360. */ void lv_example_gltf_1(void) { diff --git a/examples/libs/gltf/lv_example_gltf_2.c b/examples/libs/gltf/lv_example_gltf_2.c index a223578c8e..9001313cbe 100644 --- a/examples/libs/gltf/lv_example_gltf_2.c +++ b/examples/libs/gltf/lv_example_gltf_2.c @@ -28,7 +28,16 @@ static void timer_cb(lv_timer_t * timer) } /** - * Open a GLTF from a file and loop through the model cameras and multiple animation speeds + * @title Cycle glTF cameras and speeds + * @brief Rotate through the scene cameras and animation speeds every 5 seconds. + * + * `lv_gltf_create` fills the active screen with + * `webp_diffuse_transmission_plant.glb` loaded from drive letter `A`. The + * viewer starts at `LV_GLTF_ANIM_SPEED_HALF` with the first animation + * playing and a 45 degree downward pitch. A 5000 ms timer advances the + * active camera with `lv_gltf_set_camera` and doubles the playback rate + * with `lv_gltf_model_set_animation_speed`, wrapping back to half once it + * passes `LV_GLTF_ANIM_SPEED_4X`. */ void lv_example_gltf_2(void) { diff --git a/examples/libs/gltf/lv_example_gltf_3.c b/examples/libs/gltf/lv_example_gltf_3.c index ca8f6d4b2c..2ac60fd0b8 100644 --- a/examples/libs/gltf/lv_example_gltf_3.c +++ b/examples/libs/gltf/lv_example_gltf_3.c @@ -133,7 +133,18 @@ static void move_plant(plant_t * plant, const lv_3dpoint_t * point) } /** - * Load multiple models in a single glTF object and modify their position, rotation and scale at runtime + * @title Drag plants across a glTF scene + * @brief Pick and drag one of five glTF plants along the ground plane with a cursor model. + * + * Five copies of `webp_diffuse_transmission_plant.glb` are loaded into a + * single `lv_gltf` viewer and spaced across the ground at fixed x and z + * offsets, while `support_assets.glb` contributes a `/cursor` node hidden + * by zeroing its scale. Pointer events + * cast a ray through `lv_gltf_get_ray_from_2d_coordinate` into the ground + * plane built by `lv_get_ground_plane`. On `LV_EVENT_PRESSED` the nearest + * plant within a squared distance of `0.1` is selected; `LV_EVENT_PRESSING` + * moves the plant and cursor to the hit point and nudges rotation, and + * `LV_EVENT_RELEASED` hides the cursor again. */ void lv_example_gltf_3(void) { diff --git a/examples/libs/gltf/lv_example_gltf_4.c b/examples/libs/gltf/lv_example_gltf_4.c index 38d67c18ab..4263ef1d18 100644 --- a/examples/libs/gltf/lv_example_gltf_4.c +++ b/examples/libs/gltf/lv_example_gltf_4.c @@ -31,9 +31,17 @@ static void logo_scale_cb(lv_event_t * e) } /** - * Load a logo model once and share it across four glTF viewers in a 2x2 grid. - * Each viewer shows the logo from a different angle. - * Animate the shared model's growth - changes affect all four viewers. + * @title Share one glTF across four viewers + * @brief Animate the scale of a logo shared by four `lv_gltf` viewers arranged in a 2x2 grid. + * + * `lv_gltf_data_load_from_file` loads `lvgl_logo.glb` once, and four + * `lv_gltf` viewers sized `50%` by `50%` are aligned to each corner of the + * active screen with pitch and yaw set to +/-30 degrees so each viewer + * shows a different angle. `lv_gltf_add_model` attaches the shared model + * to all four. An `lv_anim_t` drives the root node via `anim_scale_cb` + * from 10 to 100 (0.1 to 1.0 scale) over 2000 ms with + * `lv_anim_path_ease_in_out`, a 1000 ms reverse delay, a 1500 ms reverse + * duration, a 500 ms repeat delay, and `LV_ANIM_REPEAT_INFINITE`. */ void lv_example_gltf_4(void) { diff --git a/examples/libs/gstreamer/about.md b/examples/libs/gstreamer/about.md new file mode 100644 index 0000000000..38ea1e5897 --- /dev/null +++ b/examples/libs/gstreamer/about.md @@ -0,0 +1,6 @@ +--- +title: "GStreamer" +order: 10 +--- + +Video pipeline integration for playing streams and media files inside LVGL widgets. diff --git a/examples/libs/gstreamer/lv_example_gstreamer_1.c b/examples/libs/gstreamer/lv_example_gstreamer_1.c index 3fc9504ee5..7570ffd288 100644 --- a/examples/libs/gstreamer/lv_example_gstreamer_1.c +++ b/examples/libs/gstreamer/lv_example_gstreamer_1.c @@ -21,7 +21,19 @@ static void play_pause_pressed(lv_event_t * e); static void stream_state_changed(lv_event_t * e); /** - * Loads a video from the internet using the gstreamer widget + * @title GStreamer URI player with controls + * @brief Stream a WebM clip over HTTPS with a custom play/pause button and position slider. + * + * `lv_gstreamer_create` opens the Sintel trailer through + * `LV_GSTREAMER_FACTORY_URI_DECODE` and `LV_GSTREAMER_PROPERTY_URI_DECODE`. + * A side column binds a volume slider and label to an `lv_subject_t` that + * forwards new values to `lv_gstreamer_set_volume`. A bottom bar holds a + * position label, a play/pause button whose label switches between + * `LV_SYMBOL_PLAY`, `LV_SYMBOL_PAUSE`, and `LV_SYMBOL_REFRESH`, an + * `lv_bar` bound to a position subject, and a duration label. + * `LV_EVENT_STATE_CHANGED` updates the duration text when the stream + * starts, and a timer running at `LV_DEF_REFR_PERIOD` polls + * `lv_gstreamer_get_position` to update the seek bar. */ void lv_example_gstreamer_1(void) { diff --git a/examples/libs/libjpeg_turbo/about.md b/examples/libs/libjpeg_turbo/about.md new file mode 100644 index 0000000000..3f94cd69b2 --- /dev/null +++ b/examples/libs/libjpeg_turbo/about.md @@ -0,0 +1,6 @@ +--- +title: "libjpeg-turbo" +order: 40 +--- + +Fast JPEG decoder using SIMD-accelerated libjpeg-turbo. Enable with `LV_USE_LIBJPEG_TURBO` in `lv_conf.h`. diff --git a/examples/libs/libjpeg_turbo/lv_example_libjpeg_turbo_1.c b/examples/libs/libjpeg_turbo/lv_example_libjpeg_turbo_1.c index 5cf8837e69..f0c8e4fc41 100644 --- a/examples/libs/libjpeg_turbo/lv_example_libjpeg_turbo_1.c +++ b/examples/libs/libjpeg_turbo/lv_example_libjpeg_turbo_1.c @@ -4,7 +4,13 @@ #if LV_USE_LIBJPEG_TURBO /** - * Load a JPG image + * @title Decode JPEG with libjpeg-turbo + * @brief Load a JPEG file through the libjpeg-turbo decoder and center it on the screen. + * + * An image widget is created on the active screen with its source set to + * `A:lvgl/examples/libs/libjpeg_turbo/flower.jpg`, so the libjpeg-turbo + * image decoder reads the file through the filesystem driver registered + * under drive letter `A`. */ void lv_example_libjpeg_turbo_1(void) { diff --git a/examples/libs/libpng/about.md b/examples/libs/libpng/about.md new file mode 100644 index 0000000000..3e0a514239 --- /dev/null +++ b/examples/libs/libpng/about.md @@ -0,0 +1,6 @@ +--- +title: "libpng" +order: 45 +--- + +Reference PNG decoder implementation. Enable with `LV_USE_LIBPNG` in `lv_conf.h`. diff --git a/examples/libs/libpng/lv_example_libpng_1.c b/examples/libs/libpng/lv_example_libpng_1.c index 621c74c38e..3837e1b35b 100644 --- a/examples/libs/libpng/lv_example_libpng_1.c +++ b/examples/libs/libpng/lv_example_libpng_1.c @@ -4,7 +4,14 @@ #if LV_USE_LIBPNG /** - * Open a PNG image from a file + * @title PNG from array and file with libpng + * @brief Show the same PNG decoded from an embedded array and from a file path. + * + * Two image widgets are created on the active screen. The left one binds + * to the `img_png_demo` descriptor declared with `LV_IMAGE_DECLARE`, and + * the right one reads `A:lvgl/examples/libs/libpng/png_demo.png` through + * the filesystem driver registered under drive letter `A`. Both routes + * go through the libpng image decoder. */ void lv_example_libpng_1(void) { diff --git a/examples/libs/libwebp/about.md b/examples/libs/libwebp/about.md new file mode 100644 index 0000000000..568cfe90fa --- /dev/null +++ b/examples/libs/libwebp/about.md @@ -0,0 +1,6 @@ +--- +title: "LibWebP" +order: 70 +--- + +WEBP image decoder integration. Enable with `LV_USE_LIBWEBP` in `lv_conf.h`. diff --git a/examples/libs/libwebp/lv_example_libwebp_1.c b/examples/libs/libwebp/lv_example_libwebp_1.c index 9197a4dee6..a538c7230e 100644 --- a/examples/libs/libwebp/lv_example_libwebp_1.c +++ b/examples/libs/libwebp/lv_example_libwebp_1.c @@ -4,7 +4,13 @@ #if LV_USE_LIBWEBP /** - * Load a WEBP image + * @title Decode WebP with libwebp + * @brief Load a WebP file through the libwebp decoder and center it on the screen. + * + * An image widget is created on the active screen with its source set to + * `A:lvgl/examples/libs/libwebp/rose.webp`, so the libwebp image decoder + * reads the file through the filesystem driver registered under drive + * letter `A`. */ void lv_example_libwebp_1(void) { diff --git a/examples/libs/lodepng/about.md b/examples/libs/lodepng/about.md new file mode 100644 index 0000000000..6c03051bde --- /dev/null +++ b/examples/libs/lodepng/about.md @@ -0,0 +1,6 @@ +--- +title: "LodePNG" +order: 5 +--- + +PNG image decoder integration. Enable with `LV_USE_LODEPNG` in `lv_conf.h`. diff --git a/examples/libs/lodepng/lv_example_lodepng_1.c b/examples/libs/lodepng/lv_example_lodepng_1.c index 9aba1c2a1c..bc33b0727b 100644 --- a/examples/libs/lodepng/lv_example_lodepng_1.c +++ b/examples/libs/lodepng/lv_example_lodepng_1.c @@ -2,7 +2,14 @@ #if LV_USE_LODEPNG && LV_USE_IMAGE && LV_BUILD_EXAMPLES /** - * Open a PNG image from a file and a variable + * @title PNG from array and file with LodePNG + * @brief Show the same PNG decoded from an embedded array and from a file path. + * + * Two image widgets are created on the active screen. The left one binds + * to the `img_wink_png` descriptor declared with `LV_IMAGE_DECLARE`, and + * the right one reads `A:lvgl/examples/libs/lodepng/wink.png` through + * the filesystem driver registered under drive letter `A`. Both routes + * go through the LodePNG image decoder. */ void lv_example_lodepng_1(void) { diff --git a/examples/libs/qrcode/about.md b/examples/libs/qrcode/about.md new file mode 100644 index 0000000000..a05b6b3c7f --- /dev/null +++ b/examples/libs/qrcode/about.md @@ -0,0 +1,6 @@ +--- +title: "QR-Code Generator" +order: 35 +--- + +Generates QR codes as LVGL canvas images. Enable with `LV_USE_QRCODE` in `lv_conf.h`. diff --git a/examples/libs/qrcode/lv_example_qrcode_1.c b/examples/libs/qrcode/lv_example_qrcode_1.c index 3a9f87ce63..3abb434288 100644 --- a/examples/libs/qrcode/lv_example_qrcode_1.c +++ b/examples/libs/qrcode/lv_example_qrcode_1.c @@ -3,7 +3,14 @@ #include /** - * Create a QR Code + * @title QR code with palette colors + * @brief Render a 150 px QR code encoding an LVGL URL with custom dark and light colors. + * + * A QR code widget is centered on the active screen and sized to 150 px. + * `lv_qrcode_set_dark_color` and `lv_qrcode_set_light_color` use + * darkened and lightened entries from `LV_PALETTE_BLUE` and + * `LV_PALETTE_LIGHT_BLUE`, `lv_qrcode_update` encodes `https://lvgl.io`, + * and a matching 5 px border is applied via local style properties. */ void lv_example_qrcode_1(void) { diff --git a/examples/libs/rlottie/about.md b/examples/libs/rlottie/about.md new file mode 100644 index 0000000000..a8ffe85bad --- /dev/null +++ b/examples/libs/rlottie/about.md @@ -0,0 +1,6 @@ +--- +title: "rlottie" +order: 55 +--- + +Plays Lottie vector animations inside LVGL widgets. Enable with `LV_USE_RLOTTIE` in `lv_conf.h`. diff --git a/examples/libs/rlottie/lv_example_rlottie_1.c b/examples/libs/rlottie/lv_example_rlottie_1.c index f7d215a608..f56dcd9312 100644 --- a/examples/libs/rlottie/lv_example_rlottie_1.c +++ b/examples/libs/rlottie/lv_example_rlottie_1.c @@ -3,7 +3,12 @@ #if LV_USE_RLOTTIE /** - * Load an lottie animation from flash + * @title Rlottie animation from array + * @brief Play a Lottie animation decoded from a JSON byte array in flash. + * + * `lv_rlottie_create_from_raw` builds a 100x100 Lottie widget from the + * externally declared `lv_example_rlottie_approve` JSON data, and the + * widget is centered on the active screen. */ void lv_example_rlottie_1(void) { diff --git a/examples/libs/rlottie/lv_example_rlottie_2.c b/examples/libs/rlottie/lv_example_rlottie_2.c index 5c610ab5ee..b7781ae7d6 100644 --- a/examples/libs/rlottie/lv_example_rlottie_2.c +++ b/examples/libs/rlottie/lv_example_rlottie_2.c @@ -3,7 +3,14 @@ #if LV_USE_RLOTTIE /** - * Load an lottie animation from file + * @title Rlottie animation from file + * @brief Play a Lottie JSON file loaded directly through the rlottie stdio path. + * + * `lv_rlottie_create_from_file` opens + * `lvgl/examples/libs/rlottie/lv_example_rlottie_approve.json` as a 100x100 + * widget centered on the active screen. The path has no LVGL drive letter + * because rlottie reads the file through its own STDIO API rather than + * through the LVGL filesystem. */ void lv_example_rlottie_2(void) { diff --git a/examples/libs/svg/about.md b/examples/libs/svg/about.md new file mode 100644 index 0000000000..68853ff438 --- /dev/null +++ b/examples/libs/svg/about.md @@ -0,0 +1,6 @@ +--- +title: "SVG" +order: 15 +--- + +LVGL's built-in SVG parser and renderer for scalable vector graphics. Enable with `LV_USE_SVG` in `lv_conf.h`. diff --git a/examples/libs/svg/lv_example_svg_1.c b/examples/libs/svg/lv_example_svg_1.c index 7af06b64cb..e67e0c892c 100644 --- a/examples/libs/svg/lv_example_svg_1.c +++ b/examples/libs/svg/lv_example_svg_1.c @@ -3,7 +3,14 @@ #if LV_USE_SVG && LV_USE_VECTOR_GRAPHIC /** - * Load an SVG from data + * @title SVG from inline markup + * @brief Render an SVG circle described by a literal string as an image source. + * + * A static `lv_image_dsc_t` is populated with `LV_IMAGE_HEADER_MAGIC`, a + * 450x150 display size, and a pointer to the literal SVG markup drawing + * a red circle with a blue stroke. The descriptor is handed to + * `lv_image_set_src` on an image widget placed on the active screen so + * the SVG decoder renders the markup on demand. */ void lv_example_svg_1(void) { diff --git a/examples/libs/svg/lv_example_svg_2.c b/examples/libs/svg/lv_example_svg_2.c index b4e839512f..bc483a3a91 100644 --- a/examples/libs/svg/lv_example_svg_2.c +++ b/examples/libs/svg/lv_example_svg_2.c @@ -3,7 +3,12 @@ #if LV_USE_SVG && LV_USE_VECTOR_GRAPHIC /** - * Load an SVG from a file + * @title SVG from filesystem + * @brief Load an SVG file through the LVGL filesystem and use it as an image source. + * + * An image widget is created on the active screen and its source is set to + * `A:lvgl/examples/assets/circle.svg`, so the SVG decoder reads the file + * through the filesystem driver registered under drive letter `A`. */ void lv_example_svg_2(void) { diff --git a/examples/libs/svg/lv_example_svg_3.c b/examples/libs/svg/lv_example_svg_3.c index 04ab15c659..875ee8e30c 100644 --- a/examples/libs/svg/lv_example_svg_3.c +++ b/examples/libs/svg/lv_example_svg_3.c @@ -16,6 +16,16 @@ static void event_cb(lv_event_t * e) lv_svg_node_delete(svg); } +/** + * @title Draw SVG in a draw event + * @brief Paint SVG markup directly into the screen's draw layer on `LV_EVENT_DRAW_MAIN`. + * + * `lv_obj_add_event_cb` subscribes a handler to the active screen's + * `LV_EVENT_DRAW_MAIN`. The handler parses an inline SVG string with + * `lv_svg_load_data`, calls `lv_draw_svg` against the layer returned by + * `lv_event_get_layer`, and then releases the node with + * `lv_svg_node_delete`. + */ void lv_example_svg_3(void) { lv_obj_add_event_cb(lv_screen_active(), event_cb, LV_EVENT_DRAW_MAIN, NULL); diff --git a/examples/libs/tiny_ttf/about.md b/examples/libs/tiny_ttf/about.md new file mode 100644 index 0000000000..7a684cfc7a --- /dev/null +++ b/examples/libs/tiny_ttf/about.md @@ -0,0 +1,6 @@ +--- +title: "Tiny TTF" +order: 65 +--- + +Lightweight TrueType font renderer based on stb_truetype. Enable with `LV_USE_TINY_TTF` in `lv_conf.h`. diff --git a/examples/libs/tiny_ttf/lv_example_tiny_ttf_1.c b/examples/libs/tiny_ttf/lv_example_tiny_ttf_1.c index adbeca2d6f..1e55fddd2c 100644 --- a/examples/libs/tiny_ttf/lv_example_tiny_ttf_1.c +++ b/examples/libs/tiny_ttf/lv_example_tiny_ttf_1.c @@ -2,7 +2,13 @@ #if LV_USE_TINY_TTF && LV_BUILD_EXAMPLES /** - * Load a font with Tiny_TTF + * @title Tiny TTF font from memory + * @brief Render a multi-line label with a 30 px TTF decoded from an embedded byte array. + * + * `lv_tiny_ttf_create_data` loads the external `ubuntu_font` byte array at + * 30 px. A style binds the resulting `lv_font_t` and centers text, then a + * label is placed at the center of the active screen showing a four-line + * greeting drawn with the decoded font. */ void lv_example_tiny_ttf_1(void) { diff --git a/examples/libs/tiny_ttf/lv_example_tiny_ttf_2.c b/examples/libs/tiny_ttf/lv_example_tiny_ttf_2.c index ed2617edbf..f1b86e8b03 100644 --- a/examples/libs/tiny_ttf/lv_example_tiny_ttf_2.c +++ b/examples/libs/tiny_ttf/lv_example_tiny_ttf_2.c @@ -5,7 +5,14 @@ #if LV_USE_TINY_TTF && LV_TINY_TTF_FILE_SUPPORT /** - * Load a font with Tiny_TTF from file + * @title Tiny TTF font from file + * @brief Render a multi-line label with a 30 px TTF opened from the LVGL filesystem. + * + * `lv_tiny_ttf_create_file` reads `Ubuntu-Medium.ttf` at 30 px through the + * filesystem driver registered under drive letter `A`. A style binds the + * resulting `lv_font_t` and centers text, then a label placed at the + * center of the active screen shows a four-line greeting drawn with the + * decoded font. The file path requires `LV_TINY_TTF_FILE_SUPPORT`. */ void lv_example_tiny_ttf_2(void) { diff --git a/examples/libs/tiny_ttf/lv_example_tiny_ttf_3.c b/examples/libs/tiny_ttf/lv_example_tiny_ttf_3.c index 1b7f40fe21..f01868ca09 100644 --- a/examples/libs/tiny_ttf/lv_example_tiny_ttf_3.c +++ b/examples/libs/tiny_ttf/lv_example_tiny_ttf_3.c @@ -6,7 +6,15 @@ static void font_size_observer_cb(lv_observer_t * observer, lv_subject_t * subje static lv_subject_t subject_font; /** - * Change font size with Tiny_TTF + * @title Resize Tiny TTF font with a slider + * @brief Rescale a Tiny TTF font live as a slider drives a bound subject. + * + * `lv_tiny_ttf_create_data` builds a 25 px font from the embedded + * `ubuntu_font` array and applies it to a style used by a centered + * `Hello world!` label. A slider spanning 5 to 50 is bound through + * `lv_subject_t` to a label showing the current value, and an observer + * calls `lv_tiny_ttf_set_size` followed by `lv_obj_report_style_change` + * whenever the subject updates so the label redraws at the new size. */ void lv_example_tiny_ttf_3(void) { diff --git a/examples/libs/tjpgd/about.md b/examples/libs/tjpgd/about.md new file mode 100644 index 0000000000..c6f68ff5bf --- /dev/null +++ b/examples/libs/tjpgd/about.md @@ -0,0 +1,6 @@ +--- +title: "Tiny JPEG Decompressor (TJpgDec)" +order: 50 +--- + +Small-footprint JPEG decoder suited for memory-constrained targets. Enable with `LV_USE_TJPGD` in `lv_conf.h`. diff --git a/examples/libs/tjpgd/lv_example_tjpgd_1.c b/examples/libs/tjpgd/lv_example_tjpgd_1.c index be62567610..9d9a41d3ba 100644 --- a/examples/libs/tjpgd/lv_example_tjpgd_1.c +++ b/examples/libs/tjpgd/lv_example_tjpgd_1.c @@ -2,7 +2,12 @@ #if LV_USE_TJPGD && LV_BUILD_EXAMPLES /** - * Load a JPG image + * @title Decode JPEG with TJpgDec + * @brief Load a JPEG file through the TJpgDec decoder and center it on the screen. + * + * An image widget is created on the active screen with its source set to + * `A:test_img_lvgl_logo.jpg`, so the TJpgDec image decoder reads the file + * through the filesystem driver registered under drive letter `A`. */ void lv_example_tjpgd_1(void) { diff --git a/examples/others/about.md b/examples/others/about.md new file mode 100644 index 0000000000..d3b870cf0f --- /dev/null +++ b/examples/others/about.md @@ -0,0 +1,7 @@ +--- +title: "Others" +description: "Utility modules: navigation, observers, file explorer, translation, and more." +order: 100 +--- + +This section groups auxiliary modules that do not belong to a single widget category: screen navigation helpers, the observer/subject binding system, the file explorer, translation tables, monkey test input, gesture recognizers, and similar utilities. Each page is self-contained and can be enabled in `lv_conf.h` independently of the others. diff --git a/examples/others/file_explorer/about.md b/examples/others/file_explorer/about.md new file mode 100644 index 0000000000..ee35182d90 --- /dev/null +++ b/examples/others/file_explorer/about.md @@ -0,0 +1,6 @@ +--- +title: "File Explorer" +order: 45 +--- + +Browse the filesystem through an LVGL widget. diff --git a/examples/others/file_explorer/lv_example_file_explorer_1.c b/examples/others/file_explorer/lv_example_file_explorer_1.c index f51cf9c3c9..0b78b19a9a 100644 --- a/examples/others/file_explorer/lv_example_file_explorer_1.c +++ b/examples/others/file_explorer/lv_example_file_explorer_1.c @@ -18,6 +18,17 @@ static void file_explorer_event_handler(lv_event_t * e) } } +/** + * @title File explorer with quick access + * @brief Open a file explorer on the active screen and log the selected path. + * + * `lv_file_explorer_create` builds a full-screen browser, `lv_file_explorer_set_sort` + * sorts entries by `LV_EXPLORER_SORT_KIND`, and `lv_file_explorer_open_dir` opens the + * platform root (`"C:C:/"` on Win32 or `"A:/"` on the `lv_fs` Linux driver). When + * `LV_FILE_EXPLORER_QUICK_ACCESS` is enabled, `HOME`, `VIDEO`, `PICTURES`, `MUSIC`, + * `DOCS`, and `FS` shortcuts are registered. An `LV_EVENT_ALL` callback prints the + * current path and the selected file name on every `LV_EVENT_VALUE_CHANGED`. + */ void lv_example_file_explorer_1(void) { lv_obj_t * file_explorer = lv_file_explorer_create(lv_screen_active()); diff --git a/examples/others/file_explorer/lv_example_file_explorer_2.c b/examples/others/file_explorer/lv_example_file_explorer_2.c index 17a7854657..741041efde 100644 --- a/examples/others/file_explorer/lv_example_file_explorer_2.c +++ b/examples/others/file_explorer/lv_example_file_explorer_2.c @@ -53,6 +53,18 @@ static void dd_event_handler(lv_event_t * e) } #endif +/** + * @title Quick access toggle and sort control + * @brief File explorer with a header button to hide quick access and a dropdown to change sort mode. + * + * Adds a checkable button and a dropdown into the file explorer's header + * (`lv_file_explorer_get_header`). Toggling the button adds or removes + * `LV_OBJ_FLAG_HIDDEN` on the quick access panel returned by + * `lv_file_explorer_get_quick_access_area`. The dropdown switches between + * `LV_EXPLORER_SORT_NONE` and `LV_EXPLORER_SORT_KIND` via + * `lv_file_explorer_set_sort`. A separate `LV_EVENT_ALL` handler logs the current + * path and selected file name. + */ void lv_example_file_explorer_2(void) { lv_obj_t * file_explorer = lv_file_explorer_create(lv_screen_active()); diff --git a/examples/others/file_explorer/lv_example_file_explorer_3.c b/examples/others/file_explorer/lv_example_file_explorer_3.c index 7db0e9054f..9385086260 100644 --- a/examples/others/file_explorer/lv_example_file_explorer_3.c +++ b/examples/others/file_explorer/lv_example_file_explorer_3.c @@ -61,6 +61,16 @@ static void file_explorer_event_handler(lv_event_t * e) } } +/** + * @title Custom file explorer sort + * @brief Apply a 3-way quicksort over the file table after each directory load. + * + * The file explorer is created with `LV_EXPLORER_SORT_NONE` so that default sorting + * stays out of the way. On `LV_EVENT_READY`, `lv_file_explorer_get_file_table` + * returns the underlying table and a static 3-way quicksort reorders rows by the + * kind column. `LV_EVENT_VALUE_CHANGED` still logs the current path and selected + * file name. + */ void lv_example_file_explorer_3(void) { lv_obj_t * file_explorer = lv_file_explorer_create(lv_screen_active()); diff --git a/examples/others/font_manager/about.md b/examples/others/font_manager/about.md new file mode 100644 index 0000000000..96060b2b78 --- /dev/null +++ b/examples/others/font_manager/about.md @@ -0,0 +1,6 @@ +--- +title: "Font Manager" +order: 10 +--- + +Load fonts at runtime and configure fallback chains, including image-based fonts. diff --git a/examples/others/font_manager/lv_example_font_manager_1.c b/examples/others/font_manager/lv_example_font_manager_1.c index c64777a500..40a22a28fb 100644 --- a/examples/others/font_manager/lv_example_font_manager_1.c +++ b/examples/others/font_manager/lv_example_font_manager_1.c @@ -9,6 +9,17 @@ static lv_font_manager_t * g_font_manager = NULL; +/** + * @title Font manager with a FreeType source + * @brief Register a TTF path with the font manager and render a label with it. + * + * `lv_font_manager_create(8)` builds a manager with an 8-slot recycling cache. + * `lv_font_manager_add_src_static` maps the name `"Lato-Regular"` to + * `Lato-Regular.ttf` through `lv_freetype_font_class`. `lv_font_manager_create_font` + * then resolves that name at size 24 with `LV_FREETYPE_FONT_RENDER_MODE_BITMAP`, + * `LV_FREETYPE_FONT_STYLE_NORMAL`, and `LV_FONT_KERNING_NONE`. The returned font + * is applied as the text font of a centered label reading "Hello Font Manager!". + */ void lv_example_font_manager_1(void) { /* Create font manager, with 8 fonts recycling buffers */ diff --git a/examples/others/font_manager/lv_example_font_manager_2.c b/examples/others/font_manager/lv_example_font_manager_2.c index 4a5f36f880..ddee058145 100644 --- a/examples/others/font_manager/lv_example_font_manager_2.c +++ b/examples/others/font_manager/lv_example_font_manager_2.c @@ -9,6 +9,18 @@ static lv_font_manager_t * g_font_manager = NULL; +/** + * @title Font fallback across multiple sources + * @brief Combine a TinyTTF, a FreeType emoji font, and built-in Montserrat into one fallback chain. + * + * Up to three sources are registered with `lv_font_manager_add_src_static`: + * Montserrat 14 and 32 through `lv_builtin_font_class`, `NotoColorEmoji-32.subset.ttf` + * through `lv_freetype_font_class`, and `Ubuntu-Medium.ttf` through + * `lv_tiny_ttf_font_class`. `lv_font_manager_create_font` asks for the comma-joined + * chain `"Ubuntu-Medium,NotoColorEmoji,Montserrat"` at size 32, producing a font + * that falls through each source. A centered label uses it to render ASCII text, + * an emoji, and `LV_SYMBOL_OK`. + */ void lv_example_font_manager_2(void) { /* Create font manager, with 8 fonts recycling buffers */ diff --git a/examples/others/font_manager/lv_example_font_manager_3.c b/examples/others/font_manager/lv_example_font_manager_3.c index bb5f317d91..02915ec457 100644 --- a/examples/others/font_manager/lv_example_font_manager_3.c +++ b/examples/others/font_manager/lv_example_font_manager_3.c @@ -69,6 +69,18 @@ static const lv_font_class_t imgfont_class = { .free_src_cb = imgfont_free_src_cb, }; +/** + * @title Custom image font class + * @brief Register a user-defined imgfont class that only matches a size range. + * + * The file defines an `lv_font_class_t` whose `create_cb` returns a font from + * `lv_imgfont_create` only when the requested size falls between + * `match_size_min` and `match_size_max` (70 to 80). That class is registered as + * `"Emoji"` alongside a FreeType `"Lato-Regular"` source. + * `lv_font_manager_create_font` builds the chain `"Lato-Regular,Emoji"` at size 75, + * and a centered label renders `"Quiet\uF617~"` with the emoji glyph coming from + * the image source. + */ void lv_example_font_manager_3(void) { /* Create font manager, with 8 fonts recycling buffers */ diff --git a/examples/others/fragment/about.md b/examples/others/fragment/about.md new file mode 100644 index 0000000000..afa414c43d --- /dev/null +++ b/examples/others/fragment/about.md @@ -0,0 +1,6 @@ +--- +title: "Fragment Manager" +order: 50 +--- + +Android-style fragment lifecycle and back-stack navigation via `lv_fragment_manager_t`. diff --git a/examples/others/fragment/lv_example_fragment_1.c b/examples/others/fragment/lv_example_fragment_1.c index f0c449e838..1b134c4940 100644 --- a/examples/others/fragment/lv_example_fragment_1.c +++ b/examples/others/fragment/lv_example_fragment_1.c @@ -25,6 +25,16 @@ static const lv_fragment_class_t sample_cls = { .instance_size = sizeof(struct sample_fragment_t), }; +/** + * @title Single fragment inside a container + * @brief Attach an `lv_fragment_manager_t` to a full-screen container and replace in one fragment. + * + * A full-screen `lv_obj_create` acts as the root container. An `lv_fragment_manager_t` + * is created and wired to the root's `LV_EVENT_DELETE` so + * `lv_fragment_manager_delete` runs before the children go away. The custom class + * `sample_cls` stores a name string; `lv_fragment_manager_replace` swaps it in and + * its `create_obj_cb` builds a label that prints `"Hello, Fragment!"`. + */ void lv_example_fragment_1(void) { root = lv_obj_create(lv_screen_active()); diff --git a/examples/others/fragment/lv_example_fragment_2.c b/examples/others/fragment/lv_example_fragment_2.c index da0ec924e2..c15b0b18cf 100644 --- a/examples/others/fragment/lv_example_fragment_2.c +++ b/examples/others/fragment/lv_example_fragment_2.c @@ -33,6 +33,18 @@ static const lv_fragment_class_t sample_cls = { static lv_obj_t * container = NULL; +/** + * @title Push and pop fragment stack + * @brief Build a navigation stack where Push and Pop buttons drive `lv_fragment_manager_push`/`pop`. + * + * A grid layout splits the screen into a content cell and two buttons labelled + * "Push" and "Pop". Each stacked fragment tracks its depth and a click counter, + * and its `create_obj_cb` builds a column with a depth label, a counter label, + * and a `+1` button that updates the counter. "Push" calls + * `lv_fragment_manager_push` with the current stack size as the starting depth; + * "Pop" calls `lv_fragment_manager_pop`. The root's `LV_EVENT_DELETE` tears the + * manager down. + */ void lv_example_fragment_2(void) { lv_obj_t * root = lv_obj_create(lv_screen_active()); diff --git a/examples/others/gestures/about.md b/examples/others/gestures/about.md new file mode 100644 index 0000000000..9b86970f97 --- /dev/null +++ b/examples/others/gestures/about.md @@ -0,0 +1,6 @@ +--- +title: "Gestures" +order: 5 +--- + +Detect swipe and pinch gestures on widgets. diff --git a/examples/others/gestures/lv_example_gestures.c b/examples/others/gestures/lv_example_gestures.c index eb2cfd78a4..67d83e6bb4 100644 --- a/examples/others/gestures/lv_example_gestures.c +++ b/examples/others/gestures/lv_example_gestures.c @@ -69,8 +69,16 @@ static uint32_t label_y; /** - * Entry point it creates the screen, and the label - * Set event callbacks on the label + * @title Pinch, rotate, and two-finger swipe + * @brief Transform a 300x300 rectangle with three `LV_EVENT_GESTURE` callbacks. + * + * A clickable label styled as a 300x300 rectangle is centered on the screen. + * Three callbacks are attached on `LV_EVENT_GESTURE`: one handles + * `LV_INDEV_GESTURE_PINCH` and rescales the rectangle between 0.4x and 2.0x via + * `lv_event_get_pinch_scale`, one handles `LV_INDEV_GESTURE_ROTATE` and applies + * `lv_obj_set_style_transform_rotation` around the pivot, and one handles + * `LV_INDEV_GESTURE_TWO_FINGERS_SWIPE` and writes the direction and distance + * into the label text. */ void lv_example_gestures(void) { diff --git a/examples/others/gridnav/about.md b/examples/others/gridnav/about.md new file mode 100644 index 0000000000..cc7dc20a6e --- /dev/null +++ b/examples/others/gridnav/about.md @@ -0,0 +1,6 @@ +--- +title: "Grid Navigation" +order: 20 +--- + +Navigate a grid of child widgets using keyboard or encoder input via `lv_gridnav_add`. diff --git a/examples/others/gridnav/lv_example_gridnav_1.c b/examples/others/gridnav/lv_example_gridnav_1.c index 312a0fe184..66b9157654 100644 --- a/examples/others/gridnav/lv_example_gridnav_1.c +++ b/examples/others/gridnav/lv_example_gridnav_1.c @@ -2,7 +2,15 @@ #if LV_USE_GRIDNAV && LV_USE_FLEX && LV_BUILD_EXAMPLES /** - * Demonstrate a a basic grid navigation + * @title Basic grid navigation + * @brief Two side-by-side containers, one plain and one with rollover keypad navigation. + * + * Each container is added to the default group with `lv_group_add_obj` and + * registered with `lv_gridnav_add`. The left container uses + * `LV_GRIDNAV_CTRL_NONE` and wraps 10 checkable buttons in `LV_FLEX_FLOW_ROW_WRAP`. + * The right container uses `LV_GRIDNAV_CTRL_ROLLOVER` and holds a textarea, a + * checkbox, and two switches placed by absolute position. Children are removed + * from the group with `lv_group_remove_obj` so gridnav handles keypad movement. */ void lv_example_gridnav_1(void) { diff --git a/examples/others/gridnav/lv_example_gridnav_2.c b/examples/others/gridnav/lv_example_gridnav_2.c index 8ce0013341..fcf8bd1d97 100644 --- a/examples/others/gridnav/lv_example_gridnav_2.c +++ b/examples/others/gridnav/lv_example_gridnav_2.c @@ -2,7 +2,14 @@ #if LV_USE_GRIDNAV && LV_USE_LIST && LV_BUILD_EXAMPLES /** - * Grid navigation on a list + * @title Keypad navigation across two lists + * @brief Side-by-side list widgets with distinct `lv_gridnav_ctrl_t` modes. + * + * Two `lv_list` widgets sit at the left and right edges. The left list registers + * with `LV_GRIDNAV_CTRL_NONE` and is populated with 15 `LV_SYMBOL_FILE` buttons; + * the right list uses `LV_GRIDNAV_CTRL_ROLLOVER` and holds 15 `LV_SYMBOL_DIRECTORY` + * buttons. Each list is added to the default group while every item is removed + * with `lv_group_remove_obj` so gridnav drives focus inside the list. */ void lv_example_gridnav_2(void) { diff --git a/examples/others/gridnav/lv_example_gridnav_3.c b/examples/others/gridnav/lv_example_gridnav_3.c index a608c61225..5cbfcd0de0 100644 --- a/examples/others/gridnav/lv_example_gridnav_3.c +++ b/examples/others/gridnav/lv_example_gridnav_3.c @@ -15,7 +15,16 @@ static void cont_sub_event_cb(lv_event_t * e) } /** - * Nested grid navigations + * @title Nested grid navigation with scroll-first + * @brief Outer gridnav wraps buttons and two sub-containers, one scrollable and one enter-to-focus. + * + * The outer container registers with + * `LV_GRIDNAV_CTRL_ROLLOVER | LV_GRIDNAV_CTRL_SCROLL_FIRST` so arrow keys scroll + * a long text child before moving focus. It holds two buttons, a scrollable sub + * container with placeholder text, and a second sub container that has its own + * gridnav. The inner gridnav's `LV_EVENT_KEY` handler calls `lv_group_focus_obj` + * on `LV_KEY_ENTER` and `lv_group_focus_next` on `LV_KEY_ESC` so enter steps in + * and escape steps back out. */ void lv_example_gridnav_3(void) { diff --git a/examples/others/gridnav/lv_example_gridnav_4.c b/examples/others/gridnav/lv_example_gridnav_4.c index f879c34894..214e60fa93 100644 --- a/examples/others/gridnav/lv_example_gridnav_4.c +++ b/examples/others/gridnav/lv_example_gridnav_4.c @@ -10,7 +10,15 @@ static void event_handler(lv_event_t * e) } /** - * Simple navigation on a list widget + * @title List with section separators + * @brief Twenty list buttons grouped by `lv_list_add_text` separators under gridnav rollover. + * + * A list on the left is registered with `LV_GRIDNAV_CTRL_ROLLOVER`. Every fifth + * iteration adds a non-focusable separator via `lv_list_add_text`, and each + * focusable entry is added with `lv_list_add_button` using `LV_SYMBOL_FILE`. + * Items are removed from the default group so gridnav handles movement, and + * each item's `LV_EVENT_CLICKED` callback logs its text through + * `lv_list_get_button_text`. A separate `Button` sits at the right edge. */ void lv_example_gridnav_4(void) { diff --git a/examples/others/gridnav/lv_example_gridnav_5.c b/examples/others/gridnav/lv_example_gridnav_5.c index 217daad412..db81d9e64e 100644 --- a/examples/others/gridnav/lv_example_gridnav_5.c +++ b/examples/others/gridnav/lv_example_gridnav_5.c @@ -19,7 +19,15 @@ static void roller_key_cb(lv_event_t * e) } /** - * Grid navigation for only one axis + * @title Single-axis gridnav with pass-through keys + * @brief Forward the unused axis to sliders and rollers so they mirror each other. + * + * The top container registers with `LV_GRIDNAV_CTRL_VERTICAL_MOVE_ONLY` and holds + * three sliders; left and right arrows pass through as `LV_EVENT_KEY` to the + * focused slider. The bottom container uses `LV_GRIDNAV_CTRL_HORIZONTAL_MOVE_ONLY` + * and holds three rollers; up and down pass through to the focused roller. Key + * callbacks mirror values so roller i tracks slider i through + * `lv_roller_set_selected` and `lv_slider_set_value` with `LV_ANIM_ON`. */ void lv_example_gridnav_5(void) { diff --git a/examples/others/ime/about.md b/examples/others/ime/about.md new file mode 100644 index 0000000000..3abe0f9a58 --- /dev/null +++ b/examples/others/ime/about.md @@ -0,0 +1,6 @@ +--- +title: "Pinyin IME" +order: 40 +--- + +Input method editor for typing Chinese characters via Pinyin with candidate selection. diff --git a/examples/others/ime/lv_example_ime_pinyin_1.c b/examples/others/ime/lv_example_ime_pinyin_1.c index 542ea76a77..02f24d5a68 100644 --- a/examples/others/ime/lv_example_ime_pinyin_1.c +++ b/examples/others/ime/lv_example_ime_pinyin_1.c @@ -20,6 +20,18 @@ static void ta_event_cb(lv_event_t * e) } } +/** + * @title Pinyin IME with 26-key keyboard + * @brief Wire a keyboard and candidate panel to an `lv_ime_pinyin` for Chinese input. + * + * `lv_ime_pinyin_create` is placed on the active screen with + * `lv_font_source_han_sans_sc_16_cjk` as its text font. A one-line `lv_textarea` + * receives focus; when a non-keypad indev focuses it the `lv_keyboard` is + * unhidden via `LV_OBJ_FLAG_HIDDEN` and attached with `lv_keyboard_set_textarea`. + * `LV_EVENT_CANCEL` hides the keyboard and calls `lv_indev_reset`. + * `lv_ime_pinyin_get_cand_panel` is sized to 100% by 10% and aligned above the + * keyboard. A second label shows sample Chinese text to copy. + */ void lv_example_ime_pinyin_1(void) { lv_obj_t * pinyin_ime = lv_ime_pinyin_create(lv_screen_active()); diff --git a/examples/others/ime/lv_example_ime_pinyin_2.c b/examples/others/ime/lv_example_ime_pinyin_2.c index ec58545b83..dbc43a2d5f 100644 --- a/examples/others/ime/lv_example_ime_pinyin_2.c +++ b/examples/others/ime/lv_example_ime_pinyin_2.c @@ -20,6 +20,17 @@ static void ta_event_cb(lv_event_t * e) } } +/** + * @title Pinyin IME in 9-key mode + * @brief Switch the pinyin IME into `LV_IME_PINYIN_MODE_K9` for phone-style input. + * + * Mirrors the 26-key example but calls `lv_ime_pinyin_set_mode` with + * `LV_IME_PINYIN_MODE_K9` so the attached keyboard uses a 9-key layout. The + * textarea callback hides the keyboard on `LV_EVENT_READY` instead of + * `LV_EVENT_CANCEL`, and `lv_ime_pinyin_get_cand_panel` is aligned above the + * keyboard at 100% width and 10% height. A reference label displays Chinese + * sample text to type. + */ void lv_example_ime_pinyin_2(void) { lv_obj_t * pinyin_ime = lv_ime_pinyin_create(lv_screen_active()); diff --git a/examples/others/imgfont/about.md b/examples/others/imgfont/about.md new file mode 100644 index 0000000000..041ede2da0 --- /dev/null +++ b/examples/others/imgfont/about.md @@ -0,0 +1,6 @@ +--- +title: "Image Font" +order: 35 +--- + +Render images as glyphs inside labels, useful for emoji and icon sets. diff --git a/examples/others/imgfont/lv_example_imgfont_1.c b/examples/others/imgfont/lv_example_imgfont_1.c index dd103c9050..1da7f4139d 100644 --- a/examples/others/imgfont/lv_example_imgfont_1.c +++ b/examples/others/imgfont/lv_example_imgfont_1.c @@ -30,7 +30,14 @@ static const void * get_imgfont_path(const lv_font_t * font, uint32_t unicode, u } /** - * draw img in label or span obj + * @title Image glyphs inside label text + * @brief Replace private-use code points with PNG images rendered by `lv_imgfont`. + * + * `lv_imgfont_create` builds an 80 px image font whose path callback returns an + * embedded `emoji_F617` image for `U+F617` and a file path for `U+F600` (prefixed + * with `"A:"` unless `LV_USE_FFMPEG` is enabled). The font's `fallback` is set to + * `LV_FONT_DEFAULT` so ASCII characters fall through. A centered label renders + * `"12\uF600\uF617AB"`, mixing the two emoji images with normal text. */ void lv_example_imgfont_1(void) { diff --git a/examples/others/monkey/about.md b/examples/others/monkey/about.md new file mode 100644 index 0000000000..f158f98e82 --- /dev/null +++ b/examples/others/monkey/about.md @@ -0,0 +1,6 @@ +--- +title: "Monkey" +order: 30 +--- + +Generate random input events to stress-test the UI and surface hard-to-reproduce bugs. diff --git a/examples/others/monkey/lv_example_monkey_1.c b/examples/others/monkey/lv_example_monkey_1.c index a38c6b4fa5..6d41db1a9c 100644 --- a/examples/others/monkey/lv_example_monkey_1.c +++ b/examples/others/monkey/lv_example_monkey_1.c @@ -1,6 +1,15 @@ #include "../../lv_examples.h" #if LV_USE_MONKEY && LV_BUILD_EXAMPLES +/** + * @title Pointer monkey input + * @brief Generate random pointer events with `LV_INDEV_TYPE_POINTER`. + * + * `lv_monkey_config_init` initializes a config which is then set to + * `LV_INDEV_TYPE_POINTER` with a period between 10 ms and 100 ms. + * `lv_monkey_create` registers the synthetic input device and + * `lv_monkey_set_enable(monkey, true)` starts the stream of random clicks. + */ void lv_example_monkey_1(void) { /*Create pointer monkey test*/ diff --git a/examples/others/monkey/lv_example_monkey_2.c b/examples/others/monkey/lv_example_monkey_2.c index c864114139..44826a8290 100644 --- a/examples/others/monkey/lv_example_monkey_2.c +++ b/examples/others/monkey/lv_example_monkey_2.c @@ -1,6 +1,15 @@ #include "../../lv_examples.h" #if LV_USE_MONKEY && LV_BUILD_EXAMPLES +/** + * @title Encoder monkey input + * @brief Feed random encoder steps into a new default group for focus testing. + * + * The config is set to `LV_INDEV_TYPE_ENCODER` with a 50 to 500 ms period and + * input range of -5 to 5. A fresh `lv_group_t` is created, bound to the + * monkey's indev with `lv_indev_set_group`, and installed as the default + * group. `lv_monkey_set_enable` then starts the random encoder events. + */ void lv_example_monkey_2(void) { /*Create encoder monkey test*/ diff --git a/examples/others/monkey/lv_example_monkey_3.c b/examples/others/monkey/lv_example_monkey_3.c index c4329834f3..7f629e831e 100644 --- a/examples/others/monkey/lv_example_monkey_3.c +++ b/examples/others/monkey/lv_example_monkey_3.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_USE_MONKEY && LV_BUILD_EXAMPLES +/** + * @title Button monkey input + * @brief Fire random button presses mapped to three fixed screen coordinates. + * + * The config is set to `LV_INDEV_TYPE_BUTTON` with a 50 to 500 ms period and + * an input range covering indices 0 through 2. Three points are placed along + * the top of the screen at `hor_res/4`, `hor_res/2`, and `hor_res*3/4`, then + * bound to the monkey's indev with `lv_indev_set_button_points`. + * `lv_monkey_set_enable` starts the random presses. + */ void lv_example_monkey_3(void) { static lv_point_t btn_points[3]; diff --git a/examples/others/observer/about.md b/examples/others/observer/about.md new file mode 100644 index 0000000000..456b02f657 --- /dev/null +++ b/examples/others/observer/about.md @@ -0,0 +1,6 @@ +--- +title: "Observer" +order: 55 +--- + +Bind widgets to shared state with `lv_observer_t`, so value changes propagate to subscribers automatically. diff --git a/examples/others/observer/lv_example_observer_1.c b/examples/others/observer/lv_example_observer_1.c index 332e8a5dc3..6977d81323 100644 --- a/examples/others/observer/lv_example_observer_1.c +++ b/examples/others/observer/lv_example_observer_1.c @@ -4,7 +4,14 @@ static lv_subject_t temperature_subject; /** - * A slider sends a message on value change and a label display's that value + * @title Slider and label bound to an int subject + * @brief Move a slider and watch a label 30 px below it reformat live as the shared subject updates. + * + * `temperature_subject` is initialised with `lv_subject_init_int` to 28. A + * centered slider binds to it with `lv_slider_bind_value`, and a label 30 px + * below binds with `lv_label_bind_text` using a degree-Celsius format. Moving + * the slider pushes the new value through the subject, which rewrites the + * label text. */ void lv_example_observer_1(void) { diff --git a/examples/others/observer/lv_example_observer_2.c b/examples/others/observer/lv_example_observer_2.c index 7e94756e65..1f1ae8ab62 100644 --- a/examples/others/observer/lv_example_observer_2.c +++ b/examples/others/observer/lv_example_observer_2.c @@ -8,8 +8,17 @@ static void app_init(void); static void ui_init(void); /** - * Simple PIN login screen to start an engine. - * The only interface between the UI and the application is a single "subject". + * @title PIN login via state bindings + * @brief Decouple a login UI from an engine subject using `lv_obj_bind_state_if_*`. + * + * Two int subjects are initialised: `engine_subject` for the engine state and + * `auth_state_subject` for `LOGGED_OUT`, `LOGGED_IN`, and `AUTH_FAILED`. A + * password textarea fires `LV_EVENT_READY` to set the auth subject, a log-out + * button resets it, and an observer on `auth_state_subject` writes status text + * into an info label. `lv_obj_bind_state_if_eq` and + * `lv_obj_bind_state_if_not_eq` toggle `LV_STATE_DISABLED` on the textarea, log + * out button, and a start-engine button, which itself uses `lv_obj_bind_checked` + * to drive `engine_subject`. */ void lv_example_observer_2(void) { diff --git a/examples/others/observer/lv_example_observer_3.c b/examples/others/observer/lv_example_observer_3.c index 9682238a37..05f5940fa1 100644 --- a/examples/others/observer/lv_example_observer_3.c +++ b/examples/others/observer/lv_example_observer_3.c @@ -29,11 +29,17 @@ typedef enum { } time_am_pm_t; /** - * Show how to handle a complex time setting with hour, minute, 12/24 hour mode, and AM/PM switch - * In a real application the time can be displayed on multiple screens and it's not trivial - * how and where to store the current values and how to get them. - * In this example the widgets to set the time are create/deleted dynamically, - * yet they always know what the current values are by using subjects. + * @title Time setting with a group subject + * @brief Aggregate hour, minute, format, and AM/PM subjects into one `lv_subject_init_group`. + * + * Four int subjects hold hour, minute, 12/24 format, and AM/PM. They are gathered + * into `time_subject` via `lv_subject_init_group` so a single observer can + * re-render the time label whenever any element changes. A "Set" button creates + * a bottom container with two rollers and two dropdowns bound through + * `lv_roller_bind_value` and `lv_dropdown_bind_value`; the AM/PM dropdown uses + * `lv_obj_bind_state_if_eq` to disable itself in `TIME_FORMAT_24`. A second + * observer on the format subject swaps the hour roller options between the 12 + * and 24 lists. */ void lv_example_observer_3(void) { diff --git a/examples/others/observer/lv_example_observer_4.c b/examples/others/observer/lv_example_observer_4.c index e3bf0fc095..9a3cb35101 100644 --- a/examples/others/observer/lv_example_observer_4.c +++ b/examples/others/observer/lv_example_observer_4.c @@ -12,6 +12,18 @@ static lv_subject_t slider_subject[4]; static lv_subject_t dropdown_subject[3]; static lv_subject_t roller_subject[2]; +/** + * @title Tabbed content driven by a subject + * @brief One int subject selects which set of bound widgets appears in the content area. + * + * `current_tab_subject` is watched by three observers. One rebuilds the content + * area on change, creating four sliders, three dropdowns, or two rollers bound + * to their respective subject arrays. Children are faded and slid in and out + * with `lv_anim_t` using `lv_anim_path_ease_in_out` at 300 ms. Another observer + * toggles `LV_STATE_CHECKED` on the footer buttons, and a third animates an + * indicator bar under the active button using `lv_obj_get_x_aligned` as the + * start value. + */ void lv_example_observer_4(void) { lv_subject_init_int(¤t_tab_subject, 0); diff --git a/examples/others/observer/lv_example_observer_5.c b/examples/others/observer/lv_example_observer_5.c index 2d3dbcf248..d8d63df4d4 100644 --- a/examples/others/observer/lv_example_observer_5.c +++ b/examples/others/observer/lv_example_observer_5.c @@ -19,11 +19,18 @@ static lv_subject_t fw_download_percent_subject; static lv_subject_t fw_update_status_subject; /** - * Show how to handle a complete firmware update process with observers. - * Normally it's hard to implement a firmware update process because in some cases - * - the App needs to was for the UI (wait for a button press) - * - the UI needs to wait for the App (connecting or downloading) - * With observers these complex mechanisms can be implemented a simple and clean way. + * @title Firmware update state machine + * @brief Drive a window through its update states using two int subjects. + * + * `fw_update_status_subject` holds an `lv_fw_update_state_t` value and + * `fw_download_percent_subject` tracks progress. A start button opens an + * `lv_win` whose observer renders the appropriate content: a spinner for + * connecting, an arc plus percentage label bound with `lv_arc_bind_value` + * and `lv_label_bind_text` for downloading, and a restart button for ready. + * A separate app-side observer spawns `lv_timer_t` instances that simulate + * the 2-second connect and a 50 ms per-step download. The window's close + * button pushes `FW_UPDATE_STATE_CANCEL`, which the observer uses to delete + * the window. */ void lv_example_observer_5(void) { diff --git a/examples/others/observer/lv_example_observer_6.c b/examples/others/observer/lv_example_observer_6.c index 2eefbe8004..45764c552b 100644 --- a/examples/others/observer/lv_example_observer_6.c +++ b/examples/others/observer/lv_example_observer_6.c @@ -13,7 +13,16 @@ static void switch_theme_event_cb(lv_event_t * e); static lv_subject_t theme_subject; /** - * Change between light and dark mode + * @title Theme styles with `lv_subject_add_observer_with_target` + * @brief Recolour two style sets when a theme subject flips between light and dark. + * + * `theme_subject` starts at `THEME_MODE_DARK`. A panel with ten child buttons is + * built with encapsulated factory helpers; each helper registers its own + * `lv_panel_styles_t` or `lv_button_styles_t` through + * `lv_subject_add_observer_with_target` so the observer gets the style bundle as + * its target. The observers rewrite background, shadow, text, and gradient + * colours per mode and call `lv_obj_report_style_change`. Any button click + * toggles the subject. */ void lv_example_observer_6(void) { diff --git a/examples/others/observer/lv_example_observer_7.c b/examples/others/observer/lv_example_observer_7.c index 1c278fcb4d..09eed3b61f 100644 --- a/examples/others/observer/lv_example_observer_7.c +++ b/examples/others/observer/lv_example_observer_7.c @@ -18,7 +18,17 @@ static lv_subject_t subject_room_temperature; static lv_subject_t subject_theme; /** - * Very simple and elegant way to create light and dark themes with subjects + * @title Light and dark themes via `lv_obj_bind_style` + * @brief Apply a second style only when a theme subject equals the selected value. + * + * Two subjects are created: `subject_room_temperature` for a value shown on a + * slider and label, and `subject_theme` with values 0 (light) and 1 (dark). + * Light styles are applied unconditionally; dark overrides are attached with + * `lv_obj_bind_style` tied to `subject_theme == 1` on the screen, a container, + * the slider main, indicator, and knob parts, and a dropdown. The dropdown's + * options are `"Light\nDark"` and bound with `lv_dropdown_bind_value`. + * `lv_slider_bind_value` ties the slider to the temperature subject with range + * 20 to 40. */ void lv_example_observer_7(void) { diff --git a/examples/others/snapshot/about.md b/examples/others/snapshot/about.md new file mode 100644 index 0000000000..4ca8e98b09 --- /dev/null +++ b/examples/others/snapshot/about.md @@ -0,0 +1,6 @@ +--- +title: "Snapshot" +order: 25 +--- + +Capture a widget's rendered pixels into an image buffer with `lv_snapshot_take`. diff --git a/examples/others/snapshot/lv_example_snapshot_1.c b/examples/others/snapshot/lv_example_snapshot_1.c index e0297a80ee..973fdee490 100644 --- a/examples/others/snapshot/lv_example_snapshot_1.c +++ b/examples/others/snapshot/lv_example_snapshot_1.c @@ -21,6 +21,18 @@ static void event_cb(lv_event_t * e) } } +/** + * @title Snapshot a container into an image + * @brief Capture a widget tree on press and release with `lv_snapshot_take`. + * + * A 180x180 container is filled with four star images in an + * `LV_FLEX_FLOW_ROW_WRAP` layout. A separate `lv_image` on the screen is scaled + * to 128 and rotated 300. Every star is clickable, and both `LV_EVENT_PRESSED` + * and `LV_EVENT_RELEASED` run a callback that destroys the previous snapshot + * buffer with `lv_draw_buf_destroy`, takes a fresh one via + * `lv_snapshot_take(parent, LV_COLOR_FORMAT_ARGB8888)`, and assigns it as the + * image's source. + */ void lv_example_snapshot_1(void) { LV_IMAGE_DECLARE(img_star); diff --git a/examples/others/translation/about.md b/examples/others/translation/about.md new file mode 100644 index 0000000000..7800a0b734 --- /dev/null +++ b/examples/others/translation/about.md @@ -0,0 +1,6 @@ +--- +title: "Translation" +order: 15 +--- + +Register multi-language string tables and switch locales at runtime. diff --git a/examples/others/translation/lv_example_translation_1.c b/examples/others/translation/lv_example_translation_1.c index c9c1bfbb50..eb19989e62 100644 --- a/examples/others/translation/lv_example_translation_1.c +++ b/examples/others/translation/lv_example_translation_1.c @@ -33,7 +33,16 @@ static void add_dynamic(void) } /** - * Create and use translations + * @title Static and dynamic translation packs + * @brief Register two translation sources and print labels via `lv_tr`. + * + * A static pack provides the tags `tiger`, `lion`, `rabbit`, and `elephant` in + * English, German, and Spanish through `lv_translation_add_static`. A dynamic + * pack built with `lv_translation_add_dynamic` adds the tags `table` and + * `chair` for English and German using `lv_translation_add_tag` and + * `lv_translation_set_tag_translation`. `lv_translation_set_language("de")` + * selects German and two labels render the `tiger` and `chair` translations + * through `lv_tr`. */ void lv_example_translation_1(void) { diff --git a/examples/others/translation/lv_example_translation_2.c b/examples/others/translation/lv_example_translation_2.c index d024e9b8b5..24fe5bfdd2 100644 --- a/examples/others/translation/lv_example_translation_2.c +++ b/examples/others/translation/lv_example_translation_2.c @@ -39,7 +39,15 @@ static void language_change_cb(lv_event_t * e) } /** - * Change label text when the translation language changes + * @title Live language switching from a dropdown + * @brief Refresh translated labels on `LV_EVENT_TRANSLATION_LANGUAGE_CHANGED`. + * + * A dropdown lists the entries in the `languages` array (English, Deutsch, Español). Its + * `LV_EVENT_VALUE_CHANGED` callback reads the selected string and calls + * `lv_translation_set_language`. One label is created per tag in the `tags` + * array and subscribes to `LV_EVENT_TRANSLATION_LANGUAGE_CHANGED`; the handler + * rewrites its text with `lv_tr(tag)`. The screen uses a centered column flex + * layout and starts in English. */ void lv_example_translation_2(void) { diff --git a/examples/porting/about.md b/examples/porting/about.md new file mode 100644 index 0000000000..3b135e1c3d --- /dev/null +++ b/examples/porting/about.md @@ -0,0 +1,8 @@ +--- +title: "Porting" +description: "Platform integration: OS abstraction, display drivers, input drivers." +order: 110 +flatten: true +--- + +Bringing LVGL to a new platform means supplying a tick source, a display flush callback that pushes rendered pixels to the panel, and input read callbacks for touch, keypad, or encoder devices. If you run under an RTOS, you also wire the OS primitives (threads, mutexes) through the abstraction layer. The examples here show each hook in isolation so you can port them one at a time. diff --git a/examples/porting/osal/about.md b/examples/porting/osal/about.md new file mode 100644 index 0000000000..67962f4c00 --- /dev/null +++ b/examples/porting/osal/about.md @@ -0,0 +1,6 @@ +--- +title: "OS Abstraction Layer (OSAL)" +order: 5 +--- + +Portable wrappers for OS primitives: threads, mutexes, semaphores, and timers. diff --git a/examples/porting/osal/lv_example_osal.c b/examples/porting/osal/lv_example_osal.c index 0ad8965cb7..dc756c2ecf 100644 --- a/examples/porting/osal/lv_example_osal.c +++ b/examples/porting/osal/lv_example_osal.c @@ -39,6 +39,18 @@ static lv_thread_t increment_thread; * GLOBAL FUNCTIONS **********************/ +/** + * @title Thread-safe counter with OSAL sync + * @brief Count button clicks from a worker thread using `lv_thread_sync_t`. + * + * A button is aligned near the center of the active screen and its + * `LV_EVENT_CLICKED` callback signals an `lv_thread_sync_t`. A worker + * thread created with `lv_thread_init` at `LV_THREAD_PRIO_MID` creates a + * counter label under `lv_lock` / `lv_unlock`, then loops on + * `lv_thread_sync_wait`, incrementing a press counter and updating the + * label text on each signal. The locking pairs keep label updates safe + * across the UI and worker threads. + */ void lv_example_osal(void) { lv_obj_t * counter_button; diff --git a/examples/scroll/about.md b/examples/scroll/about.md new file mode 100644 index 0000000000..07460f422c --- /dev/null +++ b/examples/scroll/about.md @@ -0,0 +1,7 @@ +--- +title: "Scrolling" +description: "Scroll-enabled containers and content." +order: 70 +--- + +Any `lv_obj_t` whose content exceeds its bounds can scroll, with per-axis control and optional snap points that lock motion to child boundaries. Scrollbars are themeable through the `LV_PART_SCROLLBAR` style part, and event callbacks let you translate, fade, or scale children as they move through the viewport. The examples demonstrate snapped paging, custom scrollbar styling, parallax-style translation, and an infinite scroll pattern. diff --git a/examples/scroll/lv_example_scroll_1.c b/examples/scroll/lv_example_scroll_1.c index 28f4764613..29c41faeea 100644 --- a/examples/scroll/lv_example_scroll_1.c +++ b/examples/scroll/lv_example_scroll_1.c @@ -39,7 +39,14 @@ static void button_event_cb(lv_event_t * e) } /** - * Demonstrate how scrolling appears automatically + * @title Automatic scrolling and save/restore + * @brief Log scroll metrics on a 200x200 panel and save or restore its scroll position. + * + * A panel is placed on the active screen with three children positioned + * outside its bounds so scrolling is needed to reach them. A callback on + * `LV_EVENT_SCROLL` logs `lv_obj_get_scroll_x/y/top/bottom/left/right`. Two + * buttons aligned with `LV_ALIGN_OUT_LEFT_MID` capture and replay the scroll + * position via `lv_obj_scroll_to` with `LV_ANIM_ON`. */ void lv_example_scroll_1(void) { diff --git a/examples/scroll/lv_example_scroll_2.c b/examples/scroll/lv_example_scroll_2.c index 2357e8cb02..ca59737f63 100644 --- a/examples/scroll/lv_example_scroll_2.c +++ b/examples/scroll/lv_example_scroll_2.c @@ -15,7 +15,14 @@ static void sw_event_cb(lv_event_t * e) } /** - * Show an example to scroll snap + * @title Horizontal scroll snap with opt-out + * @brief Snap a row of ten panels to center, skip one panel, and toggle one-at-a-time scrolling. + * + * A 280x120 flex-row panel uses `lv_obj_set_scroll_snap_x(panel, + * LV_SCROLL_SNAP_CENTER)` so each 150 px button centers as it scrolls past. + * Panel 3 removes `LV_OBJ_FLAG_SNAPPABLE` so scrolling skips over it. A + * switch aligned at the top right toggles `LV_OBJ_FLAG_SCROLL_ONE` on the + * panel, restricting scroll gestures to one panel at a time when checked. */ void lv_example_scroll_2(void) { diff --git a/examples/scroll/lv_example_scroll_3.c b/examples/scroll/lv_example_scroll_3.c index c20a48e649..3652fdd04e 100644 --- a/examples/scroll/lv_example_scroll_3.c +++ b/examples/scroll/lv_example_scroll_3.c @@ -23,7 +23,15 @@ static void float_button_event_cb(lv_event_t * e) } /** - * Create a list with a floating button + * @title Floating add button over list + * @brief Keep a circular plus button pinned to a scrollable list while it adds track entries. + * + * A 280x220 `lv_list` is seeded with two `LV_SYMBOL_AUDIO` track entries. A + * child button given `LV_OBJ_FLAG_FLOATING` and `LV_RADIUS_CIRCLE` is aligned + * to `LV_ALIGN_BOTTOM_RIGHT` so it stays over the list while it scrolls. + * Clicking the floating button appends a new "Track N" entry, moves itself + * back to the foreground with `lv_obj_move_to_index`, and calls + * `lv_obj_scroll_to_view` with `LV_ANIM_ON` to reveal the new row. */ void lv_example_scroll_3(void) { diff --git a/examples/scroll/lv_example_scroll_4.c b/examples/scroll/lv_example_scroll_4.c index a40fe6b2a2..bb04bfb69c 100644 --- a/examples/scroll/lv_example_scroll_4.c +++ b/examples/scroll/lv_example_scroll_4.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_LIST /** - * Styling the scrollbars + * @title Styled scrollbar with state transition + * @brief Restyle the `LV_PART_SCROLLBAR` of a text panel and fade it in while scrolling. + * + * A 200x100 container holds a long Lorem Ipsum label. The default scrollbar + * style is removed, then a custom `lv_style_t` sets width 4, length 20, + * padding, radius 2, `LV_OPA_70` blue fill, a darker blue border, and a + * shadow. A second style tied to `LV_STATE_SCROLLED` widens the scrollbar + * to 8 and sets `LV_OPA_COVER`, and a 200 ms `lv_style_transition_dsc_t` + * over `LV_STYLE_BG_OPA` and `LV_STYLE_WIDTH` animates between the two states. */ void lv_example_scroll_4(void) { diff --git a/examples/scroll/lv_example_scroll_5.c b/examples/scroll/lv_example_scroll_5.c index 5f0b0af71a..165823c646 100644 --- a/examples/scroll/lv_example_scroll_5.c +++ b/examples/scroll/lv_example_scroll_5.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES && LV_FONT_DEJAVU_16_PERSIAN_HEBREW /** - * Scrolling with Right To Left base direction + * @title RTL label scrolling + * @brief Scroll a wide Persian label inside an RTL container. + * + * A 200x100 container has `LV_BASE_DIR_RTL` applied to its main part. A + * child label 400 px wide, rendered with `lv_font_dejavu_16_persian_hebrew`, + * carries a Persian paragraph; the scrollbar and scroll direction reflect + * the right-to-left base direction as the label is dragged. */ void lv_example_scroll_5(void) { diff --git a/examples/scroll/lv_example_scroll_6.c b/examples/scroll/lv_example_scroll_6.c index 95288f5121..15a4360449 100644 --- a/examples/scroll/lv_example_scroll_6.c +++ b/examples/scroll/lv_example_scroll_6.c @@ -46,7 +46,16 @@ static void scroll_event_cb(lv_event_t * e) } /** - * Translate the object as they scroll + * @title Circular scroll translate effect + * @brief Bow a column of buttons along a circle while they scroll past center. + * + * A 200x200 container is given `LV_RADIUS_CIRCLE`, `clip_corner`, + * `LV_FLEX_FLOW_COLUMN`, `LV_SCROLL_SNAP_CENTER` on Y, and + * `LV_SCROLLBAR_MODE_OFF`. Twenty full-width buttons are scrolled vertically. + * An `LV_EVENT_SCROLL` callback computes each child's vertical offset from + * the container center, maps it onto a circle with radius 7/10 of the height + * via `lv_sqrt`, writes the result to `translate_x`, and fades children with + * larger offsets toward `LV_OPA_TRANSP`. */ void lv_example_scroll_6(void) { diff --git a/examples/scroll/lv_example_scroll_7.c b/examples/scroll/lv_example_scroll_7.c index 8cdc591567..f9a73d4a6f 100644 --- a/examples/scroll/lv_example_scroll_7.c +++ b/examples/scroll/lv_example_scroll_7.c @@ -89,7 +89,16 @@ static void checkbox_cb(lv_event_t * e) } /** - * Dynamically load widgets while scrolling + * @title Virtualized infinite scroll + * @brief Load numbered rows on demand and drop far-off ones as a column is scrolled. + * + * A 160x220 column container tracks the highest and lowest loaded numbers in + * `top_num` and `bottom_num`. An `LV_EVENT_SCROLL` callback adds items while + * `lv_obj_get_scroll_top` or `lv_obj_get_scroll_bottom` is under 200 and + * within the (-30, 30) range, and deletes items once those values exceed + * 600, compensating each delta with `lv_obj_scroll_by` so the view stays + * steady. Two labels report the current extremes, and a checkbox toggles + * `LV_PART_SCROLLBAR` opacity between `LV_OPA_TRANSP` and `LV_OPA_COVER`. */ void lv_example_scroll_7(void) { diff --git a/examples/scroll/lv_example_scroll_8.c b/examples/scroll/lv_example_scroll_8.c index 1f06bcf209..0f7eff7da3 100644 --- a/examples/scroll/lv_example_scroll_8.c +++ b/examples/scroll/lv_example_scroll_8.c @@ -98,6 +98,18 @@ static void cont_col_scroll_event_cb(lv_event_t * e) } } +/** + * @title Endless wrap-around scroll + * @brief Wrap items from one edge to the other so a row and column scroll without limits. + * + * Two flex containers are built: a 300x75 row and a 200x150 column, each + * filled with ten 80 px-sized buttons. Both register an `LV_EVENT_SCROLL` + * callback that detects when `lv_obj_get_scroll_x` or `lv_obj_get_scroll_y` + * reaches either edge and calls `lv_obj_move_to_index` to move the last or + * first child across, then compensates with `lv_obj_scroll_to_x` or + * `lv_obj_scroll_to_y` so the visible content stays stable and scrolling + * feels endless. Scrollbars are hidden with `LV_SCROLLBAR_MODE_OFF`. + */ void lv_example_scroll_8(void) { /* Create a scroll container with ROW flex direction */ diff --git a/examples/scroll/lv_example_scroll_9.c b/examples/scroll/lv_example_scroll_9.c index e3c8f60c2b..d87a365bba 100644 --- a/examples/scroll/lv_example_scroll_9.c +++ b/examples/scroll/lv_example_scroll_9.c @@ -11,6 +11,17 @@ static void generic_switch_event_cb(lv_event_t * e); static lv_obj_t * list; +/** + * @title Toggle scroll flags on a list + * @brief A panel of four switches enables or clears scroll behavior flags on an image list. + * + * A shadowed panel holds a ten-entry `lv_list` of `LV_SYMBOL_IMAGE` + * buttons and four rows, each pairing a label with a switch. The switches + * are wired to `LV_EVENT_VALUE_CHANGED` and add or remove + * `LV_OBJ_FLAG_SCROLLABLE`, `LV_OBJ_FLAG_SCROLL_CHAIN`, + * `LV_OBJ_FLAG_SCROLL_ELASTIC`, and `LV_OBJ_FLAG_SCROLL_MOMENTUM` on the + * list. The list is moved to the last index so the switches appear above it. + */ void lv_example_scroll_9(void) { lv_obj_t * panel = lv_obj_create(lv_screen_active()); diff --git a/examples/styles/about.md b/examples/styles/about.md new file mode 100644 index 0000000000..70a8cb1a5c --- /dev/null +++ b/examples/styles/about.md @@ -0,0 +1,7 @@ +--- +title: "Styles" +description: "The LVGL style system: properties, states, inheritance, and transitions." +order: 20 +--- + +An `lv_style_t` holds a set of property values (color, padding, border, font, and so on) that you attach to a widget, a specific part of a widget, and a state such as `LV_STATE_PRESSED` or `LV_STATE_FOCUSED`. Styles cascade through the parent/child tree, and transitions let property changes animate between states. This section covers property groups, state handling, and common composition patterns. diff --git a/examples/styles/lv_example_style_1.c b/examples/styles/lv_example_style_1.c index 073439a6b9..aafb71b7a6 100644 --- a/examples/styles/lv_example_style_1.c +++ b/examples/styles/lv_example_style_1.c @@ -2,7 +2,14 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Using the Size, Position and Padding style properties + * @title Size, position, and padding + * @brief Style an object's width, height, coordinates, and padding, then add a child label. + * + * A single `lv_style_t` sets `radius`, `width` to 150, `height` to + * `LV_SIZE_CONTENT`, vertical padding to 20, left padding to 5, and + * positions the object at `x = 50%` of the parent with `y = 80`. The + * style is applied to a base object on the active screen, and a label + * with the text `Hello` is added as a child. */ void lv_example_style_1(void) { diff --git a/examples/styles/lv_example_style_10.c b/examples/styles/lv_example_style_10.c index 396c6249d1..a745c8c036 100644 --- a/examples/styles/lv_example_style_10.c +++ b/examples/styles/lv_example_style_10.c @@ -2,7 +2,14 @@ #if LV_BUILD_EXAMPLES && LV_USE_LINE /** - * Using the drop shadow style properties + * @title Drop shadow on arc indicator + * @brief Cast a red drop shadow from an arc's indicator part. + * + * A style sets `drop_shadow_color` to red, `drop_shadow_radius = 16`, + * `drop_shadow_opa = 255`, `drop_shadow_offset_x = 5`, and + * `drop_shadow_offset_y = 10`. It is added to an `lv_arc` on + * `LV_PART_INDICATOR` so only the foreground arc casts the shadow, and + * the arc is centered on the active screen. */ void lv_example_style_10(void) { diff --git a/examples/styles/lv_example_style_11.c b/examples/styles/lv_example_style_11.c index ce1f4c23ec..c068c410e4 100644 --- a/examples/styles/lv_example_style_11.c +++ b/examples/styles/lv_example_style_11.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Creating a transition + * @title Style transitions on press + * @brief Smoothly animate color and border changes when an object is pressed. + * + * Two `lv_style_transition_dsc_t` instances animate `LV_STYLE_BG_COLOR`, + * `LV_STYLE_BORDER_COLOR`, and `LV_STYLE_BORDER_WIDTH`: the default + * transition runs for 100 ms with a 200 ms delay, while the pressed + * transition runs for 500 ms with no delay. A red pressed style is + * attached to `LV_STATE_PRESSED` on a centered base object, so pressing + * it eases to red and releasing eases back. */ void lv_example_style_11(void) { diff --git a/examples/styles/lv_example_style_12.c b/examples/styles/lv_example_style_12.c index d6e6efd498..16b3d06b0d 100644 --- a/examples/styles/lv_example_style_12.c +++ b/examples/styles/lv_example_style_12.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Using multiple styles + * @title Layered base and warning styles + * @brief Override a shared base style with a warning style on one of two objects. + * + * A `style_base` sets light blue background, border, shadow, white + * text, and a 100 pixel width. A `style_warning` overrides only + * `bg_color`, `border_color`, and `text_color` with yellow tones. Two + * labeled objects are placed on the active screen: one with only the + * base style aligned to `LV_ALIGN_LEFT_MID`, and one with the base plus + * warning styles aligned to `LV_ALIGN_RIGHT_MID`. */ void lv_example_style_12(void) { diff --git a/examples/styles/lv_example_style_13.c b/examples/styles/lv_example_style_13.c index 30f79170c1..2134b6a369 100644 --- a/examples/styles/lv_example_style_13.c +++ b/examples/styles/lv_example_style_13.c @@ -2,7 +2,14 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Local styles + * @title Local style overrides shared style + * @brief Replace a style's background color with a per-object local setting. + * + * A reusable style sets a green background and a lighter green border + * with `width = 3`. After applying it to a centered base object, + * `lv_obj_set_style_bg_color` is called with the orange palette on + * `LV_PART_MAIN`, so the object keeps the green border but shows an + * orange fill. */ void lv_example_style_13(void) { diff --git a/examples/styles/lv_example_style_14.c b/examples/styles/lv_example_style_14.c index 87ff12f45f..3769854cc0 100644 --- a/examples/styles/lv_example_style_14.c +++ b/examples/styles/lv_example_style_14.c @@ -2,7 +2,14 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Add styles to parts and states + * @title Slider indicator part and pressed state + * @brief Style a slider's indicator differently when it is pressed. + * + * One style gives the slider's `LV_PART_INDICATOR` a horizontal red + * gradient, and a second style adds a red shadow with `shadow_width = 10` + * and `shadow_spread = 3` on `LV_PART_INDICATOR | LV_STATE_PRESSED`. The + * slider is created with value 70 and centered on the active screen, so + * pressing the indicator reveals the shadow. */ void lv_example_style_14(void) { diff --git a/examples/styles/lv_example_style_15.c b/examples/styles/lv_example_style_15.c index d29a030d5e..c637a36611 100644 --- a/examples/styles/lv_example_style_15.c +++ b/examples/styles/lv_example_style_15.c @@ -51,7 +51,17 @@ static void new_theme_init_and_set(void) } /** - * Extending the current theme + * @title Extending the current theme + * @brief Create a child theme that adds a green style to every button. + * + * A first button labeled `Original theme` is added to the active screen + * under the system theme. The helper `new_theme_init_and_set` clones + * the current theme via `lv_theme_copy`, reparents it with + * `lv_theme_set_parent`, and registers an apply callback that attaches + * `style_btn` to any `lv_button_class` object. The new theme is + * assigned with `lv_display_set_theme`, and a second button labeled + * `New theme` renders with the green background and darker border. A + * `LV_EVENT_DELETE` handler on the display frees the theme. */ void lv_example_style_15(void) { diff --git a/examples/styles/lv_example_style_16.c b/examples/styles/lv_example_style_16.c index dc6a9e190f..d28f6c27a6 100644 --- a/examples/styles/lv_example_style_16.c +++ b/examples/styles/lv_example_style_16.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_BUTTON && LV_USE_LABEL /** - * Opacity and Transformations + * @title Opacity and transform + * @brief Compare a normal button with a half-opaque one and a rotated, scaled one. + * + * Three 100 by 40 buttons are stacked vertically on the active screen. + * The first uses defaults. The second sets `opa` to `LV_OPA_50` so the + * button and its label are rendered to a layer before blending. The + * third also sets `opa` to `LV_OPA_50` and applies + * `transform_rotation = 150` (15 degrees), `transform_scale = 256 + 64` + * (1.25x), and pivots the transform at `(50, 20)`. */ void lv_example_style_16(void) { diff --git a/examples/styles/lv_example_style_17.c b/examples/styles/lv_example_style_17.c index 6e7becefff..c73340eca1 100644 --- a/examples/styles/lv_example_style_17.c +++ b/examples/styles/lv_example_style_17.c @@ -4,8 +4,16 @@ #if LV_USE_DRAW_SW_COMPLEX_GRADIENTS /** - * Simulate metallic knob using conical gradient - * For best effect set LV_GRADIENT_MAX_STOPS to 8 or at least 3 + * @title Conical gradient metallic knob + * @brief Fill a circular object with a reflected conical gradient to mimic brushed metal. + * + * A fully rounded `radius = 500` style sets a black drop shadow and a + * background `lv_grad_dsc_t` built with `lv_grad_conical_init` centered + * on the object with `LV_GRAD_EXTEND_REFLECT`. The gradient uses up to + * eight grey stops depending on `LV_GRADIENT_MAX_STOPS`. The styled + * 200 by 200 object is centered on the active screen; when + * `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is disabled, a scrolling label + * announces the missing feature instead. */ void lv_example_style_17(void) { diff --git a/examples/styles/lv_example_style_18.c b/examples/styles/lv_example_style_18.c index bf63287043..b08dfd87f2 100644 --- a/examples/styles/lv_example_style_18.c +++ b/examples/styles/lv_example_style_18.c @@ -4,7 +4,16 @@ #if LV_USE_DRAW_SW_COMPLEX_GRADIENTS /** - * Using radial gradient as background + * @title Radial gradient background + * @brief Fill the screen with a purple-to-black radial gradient. + * + * A style's background `lv_grad_dsc_t` is built with + * `lv_grad_radial_init`, centered on the object and extending to the + * bottom-right corner with `LV_GRAD_EXTEND_PAD`. The stops run from + * `0x9B1842` to black. An object sized to the display resolution is + * created on the active screen and centered. When + * `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is disabled, a scrolling label + * reports the missing feature instead. */ void lv_example_style_18(void) { diff --git a/examples/styles/lv_example_style_19.c b/examples/styles/lv_example_style_19.c index cffb9fa9c2..544eda0bee 100644 --- a/examples/styles/lv_example_style_19.c +++ b/examples/styles/lv_example_style_19.c @@ -4,7 +4,17 @@ #if LV_USE_DRAW_SW_COMPLEX_GRADIENTS /** - * Using various gradients for button background + * @title Four gradient button backgrounds + * @brief Stack four buttons using horizontal, vertical, linear, and radial gradients. + * + * Two styles prepare complex gradients: a linear gradient from + * `(0%, 0%)` to `(20%, 100%)` with `LV_GRAD_EXTEND_REFLECT`, and a + * radial gradient centered at `(30%, 30%)` extending to `(100%, 100%)` + * with the same reflect mode. Four 150 by 50 buttons are aligned on + * `LV_ALIGN_CENTER`: the first two use local `bg_grad_dir` set to + * `LV_GRAD_DIR_HOR` and `LV_GRAD_DIR_VER`, and the last two apply the + * linear and radial gradient styles. A fallback label reports when + * `LV_USE_DRAW_SW_COMPLEX_GRADIENTS` is disabled. */ void lv_example_style_19(void) { diff --git a/examples/styles/lv_example_style_2.c b/examples/styles/lv_example_style_2.c index 8376e5f174..295da18a53 100644 --- a/examples/styles/lv_example_style_2.c +++ b/examples/styles/lv_example_style_2.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES /** - * Using the background style properties + * @title Background gradient fill + * @brief Apply a two-stop vertical gradient background to a centered object. + * + * A style is configured with `radius = 5` and a `lv_grad_dsc_t` holding + * two stops: a light grey at `frac = 128` and a blue at `frac = 192`, + * with `LV_GRAD_DIR_VER`. The style is applied to a base object that is + * centered on the active screen, producing a shifted vertical gradient. */ void lv_example_style_2(void) { diff --git a/examples/styles/lv_example_style_20.c b/examples/styles/lv_example_style_20.c index 2cc2b72211..a6fcf69d7a 100644 --- a/examples/styles/lv_example_style_20.c +++ b/examples/styles/lv_example_style_20.c @@ -2,7 +2,16 @@ #if LV_BUILD_EXAMPLES && LV_USE_SLIDER && LV_USE_LOG /** - * Test between a full background modal and a recolor modal + * @title Modal overlay timing + * @brief Compare a full-screen dim layer against a recolor overlay for modal dialogs. + * + * The scene from `lv_example_style_12` is reused as the background, + * then a modal overlay is drawn over it. By default a semi-transparent + * black background is set on `lv_layer_top()`; toggling the `#if 0` + * branch switches to `lv_obj_set_style_recolor` on the active screen + * instead. A slider is added to `lv_layer_top()` and centered, then + * `lv_refr_now` and `lv_tick_elaps` print the render cost of the chosen + * approach through `LV_LOG_USER`. */ void lv_example_style_20(void) { diff --git a/examples/styles/lv_example_style_21.c b/examples/styles/lv_example_style_21.c index 29e7adc50b..a2d157ed21 100644 --- a/examples/styles/lv_example_style_21.c +++ b/examples/styles/lv_example_style_21.c @@ -46,6 +46,20 @@ LV_IMAGE_DECLARE(img_transform_avatar_15); /********************** * GLOBAL FUNCTIONS **********************/ +/** + * @title Transform a card with arc and slider + * @brief Rotate and scale a styled profile card using an arc and a slider. + * + * Separate styles configure a grid-based card with shadow and rounded + * corners, a circular avatar with shadow, and a gradient like-button. + * The helper `card_create` assembles the card from an avatar image, a + * name label, and a like-button. Two cards are centered on the active + * screen; the back one is faded with `LV_OPA_50`. A large arc and a + * bottom-aligned slider drive the front card through + * `LV_EVENT_VALUE_CHANGED`: the arc writes `transform_rotation` from + * `lv_arc_get_angle_end * 10`, while the slider (range 128 to 300, + * initial 256) sets `transform_scale_x` and `transform_scale_y`. + */ void lv_example_style_21(void) { static const int32_t grid_cols[] = {LV_GRID_CONTENT, 4, LV_GRID_FR(1), LV_GRID_TEMPLATE_LAST}; diff --git a/examples/styles/lv_example_style_3.c b/examples/styles/lv_example_style_3.c index 95201ee1bd..b2a7508843 100644 --- a/examples/styles/lv_example_style_3.c +++ b/examples/styles/lv_example_style_3.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES /** - * Using the border style properties + * @title Partial border sides + * @brief Draw a border only on the bottom and right edges of an object. + * + * The style sets a grey background with `radius = 10`, then configures a + * blue border with `width = 5` and `opa = 50%`, restricted to + * `LV_BORDER_SIDE_BOTTOM | LV_BORDER_SIDE_RIGHT`. The style is applied + * to a centered base object so only two sides receive the border. */ void lv_example_style_3(void) { diff --git a/examples/styles/lv_example_style_4.c b/examples/styles/lv_example_style_4.c index a69be3927e..182f62985e 100644 --- a/examples/styles/lv_example_style_4.c +++ b/examples/styles/lv_example_style_4.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES /** - * Using the outline style properties + * @title Outline with padding gap + * @brief Wrap an object in a blue outline offset from its edge. + * + * A grey-filled style with `radius = 5` also sets `outline_width = 2`, + * `outline_color` to blue, and `outline_pad = 8` so the outline sits 8 + * pixels outside the object's border box. The styled object is centered + * on the active screen. */ void lv_example_style_4(void) { diff --git a/examples/styles/lv_example_style_5.c b/examples/styles/lv_example_style_5.c index c25a941544..4b4cde5dc9 100644 --- a/examples/styles/lv_example_style_5.c +++ b/examples/styles/lv_example_style_5.c @@ -2,7 +2,12 @@ #if LV_BUILD_EXAMPLES /** - * Using the Shadow style properties + * @title Box shadow glow + * @brief Render a soft blue shadow around a centered object. + * + * A grey-filled style with `radius = 5` sets `shadow_width = 55` and + * `shadow_color` to the main blue palette entry. Applying the style to + * a centered base object produces a wide blue glow on all sides. */ void lv_example_style_5(void) { diff --git a/examples/styles/lv_example_style_6.c b/examples/styles/lv_example_style_6.c index 59d5692696..396d9a1ed3 100644 --- a/examples/styles/lv_example_style_6.c +++ b/examples/styles/lv_example_style_6.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES && LV_USE_IMAGE /** - * Using the Image style properties + * @title Image recolor and rotation + * @brief Tint an image blue and rotate it using style properties. + * + * A style sets a grey background, a blue border, `image_recolor` to + * blue with `image_recolor_opa = 50%`, and `transform_rotation = 300` + * (30 degrees). The style is applied to an `lv_image` whose source is + * `img_cogwheel_argb`, then the image is centered on the active screen. */ void lv_example_style_6(void) { diff --git a/examples/styles/lv_example_style_7.c b/examples/styles/lv_example_style_7.c index 146fd98448..18deaabc88 100644 --- a/examples/styles/lv_example_style_7.c +++ b/examples/styles/lv_example_style_7.c @@ -2,7 +2,12 @@ #if LV_BUILD_EXAMPLES && LV_USE_ARC /** - * Using the Arc style properties + * @title Arc color and width + * @brief Style the arc stroke with a red color and thin width. + * + * A style sets `arc_color` to the main red palette entry and + * `arc_width = 4`, then applies it to an `lv_arc` centered on the + * active screen so the background arc renders as a thin red ring. */ void lv_example_style_7(void) { diff --git a/examples/styles/lv_example_style_8.c b/examples/styles/lv_example_style_8.c index 853daf4065..ec1dc607de 100644 --- a/examples/styles/lv_example_style_8.c +++ b/examples/styles/lv_example_style_8.c @@ -2,7 +2,14 @@ #if LV_BUILD_EXAMPLES && LV_USE_LABEL /** - * Using the text style properties + * @title Text color and spacing + * @brief Style a label's text color, letter spacing, line spacing, and underline. + * + * A style sets a grey background, a blue border, padding, and the text + * properties `text_color` to blue, `text_letter_space = 5`, + * `text_line_space = 20`, and `text_decor = LV_TEXT_DECOR_UNDERLINE`. + * The style is applied to a two-line label that is centered on the + * active screen. */ void lv_example_style_8(void) { diff --git a/examples/styles/lv_example_style_9.c b/examples/styles/lv_example_style_9.c index 684f631a16..86c63aea40 100644 --- a/examples/styles/lv_example_style_9.c +++ b/examples/styles/lv_example_style_9.c @@ -2,7 +2,13 @@ #if LV_BUILD_EXAMPLES && LV_USE_LINE /** - * Using the line style properties + * @title Line stroke style + * @brief Style a polyline with a thick grey stroke and rounded end caps. + * + * A style sets `line_color` to the main grey palette entry, + * `line_width = 6`, and `line_rounded = true`. The style is applied to + * an `lv_line` whose point array is set with `lv_line_set_points`, and + * the line is centered on the active screen. */ void lv_example_style_9(void) { diff --git a/examples/widgets/about.md b/examples/widgets/about.md new file mode 100644 index 0000000000..e18c815d1f --- /dev/null +++ b/examples/widgets/about.md @@ -0,0 +1,7 @@ +--- +title: "Widgets" +description: "Every built-in LVGL widget." +order: 80 +--- + +This section documents the full built-in widget set, from simple labels and buttons to charts, keyboards, and tabviews. Every widget inherits from the Base Widget, which defines the shared lifecycle, style attachment points, event dispatch, and coordinate system. Start with the Base Widget page before diving into specific widgets so the common behavior is clear. diff --git a/examples/widgets/animimg/about.md b/examples/widgets/animimg/about.md new file mode 100644 index 0000000000..d440f274ab --- /dev/null +++ b/examples/widgets/animimg/about.md @@ -0,0 +1,4 @@ +--- +title: "Animation Image" +order: 10 +--- diff --git a/examples/widgets/animimg/lv_example_animimg_1.c b/examples/widgets/animimg/lv_example_animimg_1.c index 8b8d68b471..aca7476131 100644 --- a/examples/widgets/animimg/lv_example_animimg_1.c +++ b/examples/widgets/animimg/lv_example_animimg_1.c @@ -10,6 +10,17 @@ static const lv_image_dsc_t * anim_imgs[3] = { & animimg003, }; +/** + * @title Three-frame animated image + * @brief Cycle three frames on a centered animated image widget. + * + * An `lv_animimg` is centered on the active screen and receives an + * array of three `lv_image_dsc_t` descriptors through + * `lv_animimg_set_src`. `lv_animimg_set_duration` sets one full cycle + * to 1000 ms, `lv_animimg_set_repeat_count` uses + * `LV_ANIM_REPEAT_INFINITE`, and `lv_animimg_start` kicks the + * animation off. + */ void lv_example_animimg_1(void) { lv_obj_t * animimg0 = lv_animimg_create(lv_screen_active()); diff --git a/examples/widgets/arc/about.md b/examples/widgets/arc/about.md new file mode 100644 index 0000000000..c24e025d50 --- /dev/null +++ b/examples/widgets/arc/about.md @@ -0,0 +1,4 @@ +--- +title: "Arc" +order: 15 +--- diff --git a/examples/widgets/arc/lv_example_arc_1.c b/examples/widgets/arc/lv_example_arc_1.c index 573cc34433..3c2016a4d2 100644 --- a/examples/widgets/arc/lv_example_arc_1.c +++ b/examples/widgets/arc/lv_example_arc_1.c @@ -4,6 +4,17 @@ static void value_changed_event_cb(lv_event_t * e); +/** + * @title Arc with rotating percentage label + * @brief Report the arc value on a label that orbits with the knob. + * + * A 150 by 150 arc sweeps 270 degrees starting at rotation 135 and + * begins at value 10. An `LV_EVENT_VALUE_CHANGED` callback writes the + * current value into a label as `%` and calls + * `lv_arc_rotate_obj_to_angle` with a 25 px radius so the label + * follows the knob. The initial label is primed with + * `lv_obj_send_event`. + */ void lv_example_arc_1(void) { lv_obj_t * label = lv_label_create(lv_screen_active()); diff --git a/examples/widgets/arc/lv_example_arc_2.c b/examples/widgets/arc/lv_example_arc_2.c index 62f04a7b08..feaca0bbe4 100644 --- a/examples/widgets/arc/lv_example_arc_2.c +++ b/examples/widgets/arc/lv_example_arc_2.c @@ -8,7 +8,14 @@ static void set_angle(void * obj, int32_t v) } /** - * Create an arc which acts as a loader. + * @title Arc loader animation + * @brief Centered 360 degree arc fills from 0 to 100 in a one-second loop. + * + * A centered arc has its background angles set to a full 360 degrees + * starting at rotation 270, with the knob style removed and + * `LV_OBJ_FLAG_CLICKABLE` cleared so it cannot be dragged. An + * `lv_anim_t` drives `lv_arc_set_value` from 0 to 100 across 1000 ms + * with a 500 ms repeat delay and `LV_ANIM_REPEAT_INFINITE`. */ void lv_example_arc_2(void) { diff --git a/examples/widgets/arc/lv_example_arc_3.c b/examples/widgets/arc/lv_example_arc_3.c index 9bcc9d3a35..ddaa58d6ac 100644 --- a/examples/widgets/arc/lv_example_arc_3.c +++ b/examples/widgets/arc/lv_example_arc_3.c @@ -145,6 +145,20 @@ static void create_slice(lv_obj_t * parent, int percentage, lv_color_t color) lv_obj_add_event_cb(arc, arc_click_cb, LV_EVENT_CLICKED, info); } +/** + * @title Clickable pie chart with exploding slices + * @brief Five coloured arc slices pop outward when clicked and snap back. + * + * A flex-row container holds a 150 by 150 slice canvas built from five + * overlapping arcs (12%, 18%, 26%, 24%, 20%) created with + * `LV_ARC_MODE_NORMAL`, each taking a share of the full circle via + * `lv_arc_set_bg_start_angle` and `lv_arc_set_bg_end_angle`. Each + * slice carries its own percentage label positioned along its midpoint + * and enables `LV_OBJ_FLAG_ADV_HITTEST` so clicks register on the + * wedge shape. An `LV_EVENT_CLICKED` callback animates the slice 20 px + * outward along the slice midpoint over 200 ms, reversing it on a + * second click and pulling any previously exploded slice back in. + */ void lv_example_arc_3(void) { /* Root container: flex row */ diff --git a/examples/widgets/arclabel/about.md b/examples/widgets/arclabel/about.md new file mode 100644 index 0000000000..ebf25844de --- /dev/null +++ b/examples/widgets/arclabel/about.md @@ -0,0 +1,6 @@ +--- +title: "Arc Label" +order: 20 +--- + +A label that renders text along a curved path, configured via `lv_arclabel_set_angle_start` and related APIs. diff --git a/examples/widgets/arclabel/lv_example_arclabel_1.c b/examples/widgets/arclabel/lv_example_arclabel_1.c index 104f77e765..1b8003e4fe 100644 --- a/examples/widgets/arclabel/lv_example_arclabel_1.c +++ b/examples/widgets/arclabel/lv_example_arclabel_1.c @@ -5,6 +5,20 @@ static const char * ARCLABEL_TEXT = "I'm on an #FA7C45 ARC#! Centered with #12c2E9 C##8B68E8 O##c471ed L##B654E5 O##C84AB2 R##DB417A F##f64659 U##ff8888 L# feature!\n"; +/** + * @title Curved text along circular paths + * @brief Four arclabels wrap recoloured text and slogans around concentric radii. + * + * A black screen hosts four `lv_arclabel` objects. An inner 200 by + * 200 arclabel curves a recoloured string counter-clockwise at 80% + * radius with trailing vertical alignment, and an outer arclabel + * paints the same string clockwise at 100% radius with leading + * alignment. Two 300 by 200 slogans (`STAY HUNGRY`, `STAY FOOLISH`) + * sit at a fixed 150 px radius with a 30 px offset, amber colour, + * and counter-clockwise direction. When available, + * `lv_font_montserrat_18` is applied to the inner pair and + * `lv_font_montserrat_24` to the slogans. + */ void lv_example_arclabel_1(void) { lv_obj_t * arclabel_inner = NULL; diff --git a/examples/widgets/bar/about.md b/examples/widgets/bar/about.md new file mode 100644 index 0000000000..aee4951729 --- /dev/null +++ b/examples/widgets/bar/about.md @@ -0,0 +1,4 @@ +--- +title: "Bar" +order: 25 +--- diff --git a/examples/widgets/bar/lv_example_bar_1.c b/examples/widgets/bar/lv_example_bar_1.c index 59a49bd6ae..49de0beb5f 100644 --- a/examples/widgets/bar/lv_example_bar_1.c +++ b/examples/widgets/bar/lv_example_bar_1.c @@ -1,6 +1,15 @@ #include "../../lv_examples.h" #if LV_USE_BAR && LV_BUILD_EXAMPLES +/** + * @title Simple bar at 70 percent + * @brief A default 200 x 20 bar centered on the screen with its value set to 70. + * + * `lv_bar_create` produces a themed progress bar that is sized to + * 200 x 20 px and centered on the active screen. `lv_bar_set_value` with + * `LV_ANIM_OFF` snaps the indicator to 70 on the default 0 to 100 range + * without animating. + */ void lv_example_bar_1(void) { lv_obj_t * bar1 = lv_bar_create(lv_screen_active()); diff --git a/examples/widgets/bar/lv_example_bar_2.c b/examples/widgets/bar/lv_example_bar_2.c index 1080229317..c805b70e02 100644 --- a/examples/widgets/bar/lv_example_bar_2.c +++ b/examples/widgets/bar/lv_example_bar_2.c @@ -2,7 +2,15 @@ #if LV_USE_BAR && LV_BUILD_EXAMPLES /** - * Example of styling the bar + * @title Custom background and indicator styles + * @brief Restyle the bar background and indicator, then fill it to 100 with animation. + * + * The theme styles are removed and two local styles are applied: a background + * style with a 2 px `LV_PALETTE_BLUE` border, 6 px padding to shrink the + * indicator inset, and a 1000 ms `anim_duration`, plus an + * `LV_PART_INDICATOR` style with a solid blue fill and 3 px radius. + * `lv_bar_set_value(bar, 100, LV_ANIM_ON)` drives the indicator up to full + * using the configured duration. */ void lv_example_bar_2(void) { diff --git a/examples/widgets/bar/lv_example_bar_3.c b/examples/widgets/bar/lv_example_bar_3.c index ab6fda4ace..0fb5ff2667 100644 --- a/examples/widgets/bar/lv_example_bar_3.c +++ b/examples/widgets/bar/lv_example_bar_3.c @@ -7,7 +7,14 @@ static void set_temp(void * bar, int32_t temp) } /** - * A temperature meter example + * @title Vertical gradient temperature meter + * @brief A tall bar ranged from -20 to 40 that animates endlessly between the extremes. + * + * A 20 x 200 vertical bar is centered on the active screen and given an + * `LV_PART_INDICATOR` style with a red-to-blue `LV_GRAD_DIR_VER` gradient. + * `lv_bar_set_range` maps the values to -20 through 40, and an `lv_anim_t` + * sweeps `lv_bar_set_value` from -20 to 40 over 3000 ms with a matching + * reverse duration, repeating with `LV_ANIM_REPEAT_INFINITE`. */ void lv_example_bar_3(void) { diff --git a/examples/widgets/bar/lv_example_bar_4.c b/examples/widgets/bar/lv_example_bar_4.c index 2a6f4db672..99a1ef247d 100644 --- a/examples/widgets/bar/lv_example_bar_4.c +++ b/examples/widgets/bar/lv_example_bar_4.c @@ -2,7 +2,14 @@ #if LV_USE_BAR && LV_BUILD_EXAMPLES /** - * Bar with stripe pattern and ranged value + * @title Ranged bar with tiled stripe pattern + * @brief A 260 x 20 bar filled between 20 and 90 with a tiled skewed-stripe overlay. + * + * `LV_IMAGE_DECLARE(img_skew_strip)` provides the stripe asset, and an + * `LV_PART_INDICATOR` style sets it as a tiled `bg_image_src` at 30% opacity. + * `lv_bar_set_mode(bar, LV_BAR_MODE_RANGE)` unlocks a configurable start + * value; `lv_bar_set_start_value` and `lv_bar_set_value` fill only the 20 + * to 90 portion of the track with the stripes on top of the theme color. */ void lv_example_bar_4(void) { diff --git a/examples/widgets/bar/lv_example_bar_5.c b/examples/widgets/bar/lv_example_bar_5.c index 75b9235055..ef81f37346 100644 --- a/examples/widgets/bar/lv_example_bar_5.c +++ b/examples/widgets/bar/lv_example_bar_5.c @@ -2,7 +2,13 @@ #if LV_USE_BAR && LV_BUILD_EXAMPLES /** - * Bar with LTR and RTL base direction + * @title LTR and RTL base direction + * @brief Two 200 x 20 bars at value 70, one filling from the left, one from the right. + * + * The first bar uses the default base direction and fills left-to-right; the + * second sets `LV_BASE_DIR_RTL` through `lv_obj_set_style_base_dir` so the + * indicator grows from the right edge. Each bar has an explanatory label + * aligned above it with `LV_ALIGN_OUT_TOP_MID` to make the direction obvious. */ void lv_example_bar_5(void) { diff --git a/examples/widgets/bar/lv_example_bar_6.c b/examples/widgets/bar/lv_example_bar_6.c index be8bcf1cbb..37d83b4647 100644 --- a/examples/widgets/bar/lv_example_bar_6.c +++ b/examples/widgets/bar/lv_example_bar_6.c @@ -51,7 +51,16 @@ static void event_cb(lv_event_t * e) } /** - * Custom drawer on the bar to display the current value + * @title Animated bar with custom value label + * @brief Draw the live value inside or beside the indicator via `LV_EVENT_DRAW_MAIN_END`. + * + * A 200 x 20 bar with range 0 to 100 is animated by `lv_anim_t` from 0 to + * 100 over 4000 ms with a matching reverse duration and + * `LV_ANIM_REPEAT_INFINITE`. On each `LV_EVENT_DRAW_MAIN_END` the callback + * measures the indicator width: when it is wider than the text plus 20 px + * the value is drawn in white inside the indicator at `LV_ALIGN_RIGHT_MID`, + * otherwise it is drawn in black outside the indicator with + * `LV_ALIGN_OUT_RIGHT_MID`. */ void lv_example_bar_6(void) { diff --git a/examples/widgets/bar/lv_example_bar_7.c b/examples/widgets/bar/lv_example_bar_7.c index 618a1e9198..278a9b94ad 100644 --- a/examples/widgets/bar/lv_example_bar_7.c +++ b/examples/widgets/bar/lv_example_bar_7.c @@ -2,7 +2,13 @@ #if LV_USE_BAR && LV_BUILD_EXAMPLES /** - * Bar with opposite direction + * @title Vertical bar filling top to bottom + * @brief A 20 x 180 vertical bar with a reversed 100-to-0 range at value 70. + * + * `lv_bar_set_range(bar_tob, 100, 0)` flips the indicator so it grows from + * the top edge downward instead of bottom-up. `lv_bar_set_value` pins the + * value at 70, and a label placed with `LV_ALIGN_OUT_TOP_MID` names the + * direction above the bar. */ void lv_example_bar_7(void) { diff --git a/examples/widgets/button/about.md b/examples/widgets/button/about.md new file mode 100644 index 0000000000..1ae6f97995 --- /dev/null +++ b/examples/widgets/button/about.md @@ -0,0 +1,4 @@ +--- +title: "Button" +order: 30 +--- diff --git a/examples/widgets/button/lv_example_button_2.c b/examples/widgets/button/lv_example_button_2.c index 441901e58e..0d4f9544b8 100644 --- a/examples/widgets/button/lv_example_button_2.c +++ b/examples/widgets/button/lv_example_button_2.c @@ -2,7 +2,16 @@ #if LV_USE_BUTTON && LV_BUILD_EXAMPLES /** - * Style a button from scratch + * @title Style a button from scratch + * @brief Build a custom blue button with a vertical gradient and a pressed-state outline animation. + * + * The theme styles are removed from a centered button and two local `lv_style_t` + * values are applied instead: one for the default state with a + * `LV_PALETTE_BLUE` vertical gradient, grey border, drop shadow, and white + * text; another for `LV_STATE_PRESSED` that darkens the gradient, nudges the + * button down by 5 px, and runs a 300 ms linear transition on + * `LV_STYLE_OUTLINE_WIDTH` and `LV_STYLE_OUTLINE_OPA` to fade a 30 px outline + * out while pressed. */ void lv_example_button_2(void) { diff --git a/examples/widgets/button/lv_example_button_3.c b/examples/widgets/button/lv_example_button_3.c index d68038563d..3ad39c1287 100644 --- a/examples/widgets/button/lv_example_button_3.c +++ b/examples/widgets/button/lv_example_button_3.c @@ -2,7 +2,15 @@ #if LV_BUILD_EXAMPLES && LV_USE_BUTTON /** - * Create a style transition on a button to act like a gum when clicked + * @title Gum-like press transition + * @brief Squash and stretch a button on press using style transitions. + * + * A centered button labelled `Gum` is given two styles. The pressed style + * widens the button by 10 px, shrinks the height by 10 px, and bumps + * `LV_STYLE_TEXT_LETTER_SPACE` to 10 px with a 250 ms + * `lv_anim_path_ease_in_out` transition. The default style uses the same + * property list with `lv_anim_path_overshoot` and a 100 ms delay so the press + * animation stays visible on a quick tap before it rubber-bands back. */ void lv_example_button_3(void) { diff --git a/examples/widgets/buttonmatrix/about.md b/examples/widgets/buttonmatrix/about.md new file mode 100644 index 0000000000..ae759555f0 --- /dev/null +++ b/examples/widgets/buttonmatrix/about.md @@ -0,0 +1,6 @@ +--- +title: "Button Matrix" +order: 35 +--- + +A grid of buttons defined from a single string map, emitting `LV_EVENT_VALUE_CHANGED` with the pressed button's index. diff --git a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_1.c b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_1.c index f6abb78789..d0e247d278 100644 --- a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_1.c +++ b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_1.c @@ -18,6 +18,19 @@ static const char * btnm_map[] = {"1", "2", "3", "4", "5", "\n", "Action1", "Action2", "" }; +/** + * @title Numeric keypad with action row + * @brief A 3-row button matrix with a checkable Action1 button and a checked Action2 button. + * + * `lv_buttonmatrix_set_map` lays out digits `1` through `0` on two rows and + * `Action1`/`Action2` on a third, where the newline strings split the rows. + * `Action1` is made twice as wide as `Action2` via + * `lv_buttonmatrix_set_button_width` and marked + * `LV_BUTTONMATRIX_CTRL_CHECKABLE`; `Action2` starts in the + * `LV_BUTTONMATRIX_CTRL_CHECKED` state. The callback subscribes to + * `LV_EVENT_ALL` and logs the text of the button that fired + * `LV_EVENT_VALUE_CHANGED`. + */ void lv_example_buttonmatrix_1(void) { lv_obj_t * btnm1 = lv_buttonmatrix_create(lv_screen_active()); diff --git a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_2.c b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_2.c index 273024daa3..e6f621974d 100644 --- a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_2.c +++ b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_2.c @@ -81,7 +81,16 @@ static void event_cb(lv_event_t * e) } /** - * Add custom drawer to the button matrix to customize buttons one by one + * @title Per-button custom drawing + * @brief Rewrite individual button draw descriptors through `LV_EVENT_DRAW_TASK_ADDED`. + * + * A centered button matrix is flagged with `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` + * and subscribes to `LV_EVENT_DRAW_TASK_ADDED`. For each `LV_PART_ITEMS` draw + * task the callback inspects `base_dsc->id1`. Button index 1 becomes a blue + * rectangular button with an offset shadow and a white label. Button 2 + * becomes a red `LV_RADIUS_CIRCLE` button that darkens on press. Button 3 + * hides its label and draws the `img_star` image centered in the fill area + * with a 30% black recolor while pressed. */ void lv_example_buttonmatrix_2(void) { diff --git a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_3.c b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_3.c index b019124174..8318763451 100644 --- a/examples/widgets/buttonmatrix/lv_example_buttonmatrix_3.c +++ b/examples/widgets/buttonmatrix/lv_example_buttonmatrix_3.c @@ -22,7 +22,16 @@ static void event_cb(lv_event_t * e) } /** - * Make a button group (pagination) + * @title Pagination button group + * @brief A pill-shaped matrix with arrow buttons that step through numbered pages. + * + * A 225 x 35 button matrix holds `LV_SYMBOL_LEFT`, the digits `1` to `5`, and + * `LV_SYMBOL_RIGHT`. A background style with `LV_RADIUS_CIRCLE` and + * `clip_corner` gives the pill shape, and an `LV_PART_ITEMS` style draws a + * 50% grey `LV_BORDER_SIDE_INTERNAL` divider between buttons. Only the number + * buttons are `LV_BUTTONMATRIX_CTRL_CHECKABLE` and `lv_buttonmatrix_set_one_checked` + * enforces a single selection; the `LV_EVENT_VALUE_CHANGED` callback moves + * the checked state one slot left or right when the arrow buttons fire. */ void lv_example_buttonmatrix_3(void) { diff --git a/examples/widgets/calendar/about.md b/examples/widgets/calendar/about.md new file mode 100644 index 0000000000..bb16bb1693 --- /dev/null +++ b/examples/widgets/calendar/about.md @@ -0,0 +1,4 @@ +--- +title: "Calendar" +order: 40 +--- diff --git a/examples/widgets/calendar/lv_example_calendar_1.c b/examples/widgets/calendar/lv_example_calendar_1.c index 35d0068348..59c3d893d8 100644 --- a/examples/widgets/calendar/lv_example_calendar_1.c +++ b/examples/widgets/calendar/lv_example_calendar_1.c @@ -14,6 +14,19 @@ static void event_handler(lv_event_t * e) } } +/** + * @title Calendar with highlighted days + * @brief Show February 2021 with three highlighted dates and log the tapped day. + * + * A 185x230 `lv_calendar` is placed below screen center with today set + * to 2021-02-23 via `lv_calendar_set_today_date` and the shown month + * fixed by `lv_calendar_set_month_shown`. A static array of three + * `lv_calendar_date_t` entries is registered through + * `lv_calendar_set_highlighted_dates`. The `LV_EVENT_VALUE_CHANGED` + * callback reads `lv_calendar_get_pressed_date` and logs the tapped + * day. If `LV_USE_CALENDAR_HEADER_DROPDOWN` or `_ARROW` is available + * the matching header is attached. + */ void lv_example_calendar_1(void) { lv_obj_t * calendar = lv_calendar_create(lv_screen_active()); diff --git a/examples/widgets/calendar/lv_example_calendar_2.c b/examples/widgets/calendar/lv_example_calendar_2.c index 5b26b96d4e..d81e35f2df 100644 --- a/examples/widgets/calendar/lv_example_calendar_2.c +++ b/examples/widgets/calendar/lv_example_calendar_2.c @@ -1,6 +1,19 @@ #include "../../lv_examples.h" #if LV_USE_CALENDAR && LV_USE_CALENDAR_CHINESE && LV_BUILD_EXAMPLES +/** + * @title Chinese calendar mode + * @brief Render a calendar with Chinese lunar annotations for March 2024. + * + * A 300x300 `lv_calendar` is aligned to the top center of the active + * screen with today set to 2024-03-22 via `lv_calendar_set_today_date` + * and the shown month fixed by `lv_calendar_set_month_shown`. An arrow + * or dropdown header is attached when available. + * `lv_calendar_set_chinese_mode` enables lunar labels and the CJK font + * `lv_font_source_han_sans_sc_14_cjk` is applied on `LV_PART_MAIN`. + * When the Chinese calendar is disabled the example falls back to a + * centered "not enabled" label. + */ void lv_example_calendar_2(void) { lv_obj_t * calendar = lv_calendar_create(lv_screen_active()); diff --git a/examples/widgets/canvas/about.md b/examples/widgets/canvas/about.md new file mode 100644 index 0000000000..df5e59a7be --- /dev/null +++ b/examples/widgets/canvas/about.md @@ -0,0 +1,4 @@ +--- +title: "Canvas" +order: 45 +--- diff --git a/examples/widgets/canvas/lv_example_canvas_1.c b/examples/widgets/canvas/lv_example_canvas_1.c index 5d146f9350..c0b4cf7acc 100644 --- a/examples/widgets/canvas/lv_example_canvas_1.c +++ b/examples/widgets/canvas/lv_example_canvas_1.c @@ -4,6 +4,17 @@ #define CANVAS_WIDTH 200 #define CANVAS_HEIGHT 150 +/** + * @title Rotated RGB565 canvas onto ARGB8888 + * @brief Render a rounded rectangle and label on an RGB565 canvas, then rotate the result onto an ARGB8888 canvas. + * + * Two 200x150 canvases are centered on the active screen. The first uses + * `LV_COLOR_FORMAT_RGB565` and draws a gradient rounded rectangle with + * `lv_draw_rect` and orange text with `lv_draw_label`. The second uses + * `LV_COLOR_FORMAT_ARGB8888`, takes the first canvas as an image via + * `lv_draw_buf_to_image`, and blits it with `lv_draw_image` rotated by + * 120 degrees around the canvas center. + */ void lv_example_canvas_1(void) { lv_draw_rect_dsc_t rect_dsc; diff --git a/examples/widgets/canvas/lv_example_canvas_10.c b/examples/widgets/canvas/lv_example_canvas_10.c index 4775be0110..8556440574 100644 --- a/examples/widgets/canvas/lv_example_canvas_10.c +++ b/examples/widgets/canvas/lv_example_canvas_10.c @@ -5,7 +5,15 @@ #define CANVAS_HEIGHT 100 /** - *Blur an area on the canvas + * @title Frosted glass blur region + * @brief Blur a rounded rectangle area of a canvas and overlay a tinted label on it. + * + * A 100x100 `LV_COLOR_FORMAT_RGB565` canvas is centered and filled with + * light grey. An underlined red background label is painted across the + * canvas. `lv_draw_blur` is then called over area {20,30,80,70} with an + * `lv_draw_blur_dsc_t` whose `blur_radius` is 8 and `corner_radius` is + * 10. A 30% opacity blue rounded fill and a black centered "Hello + * world" label are layered on top of the blurred region. */ void lv_example_canvas_10(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_11.c b/examples/widgets/canvas/lv_example_canvas_11.c index 528d5a7c21..3d44570b7f 100644 --- a/examples/widgets/canvas/lv_example_canvas_11.c +++ b/examples/widgets/canvas/lv_example_canvas_11.c @@ -48,6 +48,16 @@ static void timer_cb(lv_timer_t * timer) counter++; } +/** + * @title Animated wave text on canvas + * @brief Draw a rainbow string on a sine wave, redrawn each frame for a sliding effect. + * + * A 300x200 `LV_COLOR_FORMAT_ARGB8888` canvas is centered on the active + * screen. A 16 ms `lv_timer` clears the canvas to white and walks the + * characters of a fixed string along `y = sin(x) * 40`, offset by a + * counter. Each letter is rendered with `lv_draw_letter` using its + * tangent as `rotation` and an HSV-derived color. + */ void lv_example_canvas_11(void) { /*Create a buffer for the canvas*/ @@ -65,3 +75,4 @@ void lv_example_canvas_11(void) } #endif + diff --git a/examples/widgets/canvas/lv_example_canvas_12.c b/examples/widgets/canvas/lv_example_canvas_12.c index d732710469..be833708ca 100644 --- a/examples/widgets/canvas/lv_example_canvas_12.c +++ b/examples/widgets/canvas/lv_example_canvas_12.c @@ -50,6 +50,17 @@ static void timer_cb(lv_timer_t * timer) counter++; } +/** + * @title Windstorm text along a curve + * @brief Scatter characters along an amplitude-growing sine curve, redrawn per frame with shifting colors. + * + * A 300x200 `LV_COLOR_FORMAT_ARGB8888` canvas is centered on the active + * screen. A 16 ms `lv_timer` clears the canvas to white and places each + * letter of a fixed string on a curve whose X uses `cos` and whose Y + * blends index-scaled `sin` with the counter, producing a spreading + * windstorm shape. Letters are drawn with `lv_draw_letter`, rotated by + * the tangent and colored via `lv_color_hsv_to_rgb`. + */ void lv_example_canvas_12(void) { /*Create a buffer for the canvas*/ diff --git a/examples/widgets/canvas/lv_example_canvas_2.c b/examples/widgets/canvas/lv_example_canvas_2.c index 947af2262b..12ea6505a2 100644 --- a/examples/widgets/canvas/lv_example_canvas_2.c +++ b/examples/widgets/canvas/lv_example_canvas_2.c @@ -5,7 +5,14 @@ #define CANVAS_HEIGHT 40 /** - * Create a transparent canvas with transparency + * @title Per-pixel alpha bands on ARGB8888 + * @brief Fade horizontal blue bands from 50% to 20% to 0% opacity using `lv_canvas_set_px`. + * + * The active screen is tinted light red and an 80x40 canvas with + * `LV_COLOR_FORMAT_ARGB8888` is centered on it. The canvas is filled + * solid blue, then three row bands are overwritten pixel by pixel with + * `lv_canvas_set_px` at `LV_OPA_50`, `LV_OPA_20`, and `LV_OPA_0`, so + * the underlying screen color shows through progressively. */ void lv_example_canvas_2(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_3.c b/examples/widgets/canvas/lv_example_canvas_3.c index d22b131738..388f0b93f9 100644 --- a/examples/widgets/canvas/lv_example_canvas_3.c +++ b/examples/widgets/canvas/lv_example_canvas_3.c @@ -5,7 +5,14 @@ #define CANVAS_HEIGHT 50 /** - * Draw a rectangle to the canvas + * @title Rectangle with border and outline + * @brief Draw a red rounded rectangle with a blue border and a green outline onto a canvas. + * + * A 50x50 `LV_COLOR_FORMAT_ARGB8888` canvas is centered and filled with + * a light grey background. An `lv_draw_rect_dsc_t` is populated with a + * red fill, radius 5, a 3 px blue border, and a 2 px green outline at + * `LV_OPA_50`, then painted into area {10,10,40,30} via `lv_draw_rect` + * on a layer opened with `lv_canvas_init_layer`. */ void lv_example_canvas_3(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_4.c b/examples/widgets/canvas/lv_example_canvas_4.c index 91311afc58..ee0f5e661a 100644 --- a/examples/widgets/canvas/lv_example_canvas_4.c +++ b/examples/widgets/canvas/lv_example_canvas_4.c @@ -5,7 +5,14 @@ #define CANVAS_HEIGHT 50 /** - * Draw a text to the canvas + * @title Underlined label on canvas + * @brief Paint a red "Hello" string in Montserrat 18 with an underline decoration onto a canvas. + * + * A 50x50 `LV_COLOR_FORMAT_ARGB8888` canvas is centered on the active + * screen and filled with a light grey background. An + * `lv_draw_label_dsc_t` is configured with `lv_font_montserrat_18`, + * `LV_TEXT_DECOR_UNDERLINE`, and red text, then rendered via + * `lv_draw_label` inside a canvas layer. */ void lv_example_canvas_4(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_5.c b/examples/widgets/canvas/lv_example_canvas_5.c index 626651457f..34868a501f 100644 --- a/examples/widgets/canvas/lv_example_canvas_5.c +++ b/examples/widgets/canvas/lv_example_canvas_5.c @@ -5,7 +5,14 @@ #define CANVAS_HEIGHT 50 /** - * Draw an arc to the canvas + * @title Arc primitive on canvas + * @brief Draw a 10 px wide red arc spanning 0 to 220 degrees on a canvas. + * + * A 50x50 `LV_COLOR_FORMAT_ARGB8888` canvas is centered with a light + * grey background. An `lv_draw_arc_dsc_t` is built with center (25,25), + * radius 15, width 10, and `start_angle`/`end_angle` of 0 and 220, then + * rendered with `lv_draw_arc` into a layer opened via + * `lv_canvas_init_layer`. */ void lv_example_canvas_5(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_6.c b/examples/widgets/canvas/lv_example_canvas_6.c index d0136f1e1a..658caf993c 100644 --- a/examples/widgets/canvas/lv_example_canvas_6.c +++ b/examples/widgets/canvas/lv_example_canvas_6.c @@ -5,7 +5,14 @@ #define CANVAS_HEIGHT 50 /** - * Draw an image to the canvas + * @title Image blit via raw buffer + * @brief Attach a raw ARGB8888 pixel buffer to a canvas and blit a star image into it. + * + * A 50x50 canvas is backed by a static byte buffer sized with + * `LV_CANVAS_BUF_SIZE` and bound via `lv_canvas_set_buffer` in + * `LV_COLOR_FORMAT_ARGB8888`. After filling with light grey, the + * declared `img_star` image is drawn at offset (10,10) using + * `lv_draw_image` on a canvas layer. */ void lv_example_canvas_6(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_7.c b/examples/widgets/canvas/lv_example_canvas_7.c index 05dfc375bb..a0519c5614 100644 --- a/examples/widgets/canvas/lv_example_canvas_7.c +++ b/examples/widgets/canvas/lv_example_canvas_7.c @@ -5,7 +5,13 @@ #define CANVAS_HEIGHT 50 /** - * Draw a line to the canvas + * @title Rounded-end line on canvas + * @brief Draw a 4 px red line with rounded caps from (15,15) to (35,10) on a canvas. + * + * A 50x50 `LV_COLOR_FORMAT_ARGB8888` canvas is centered and filled with + * light grey. An `lv_draw_line_dsc_t` is configured with width 4, + * `round_start` and `round_end` set, and endpoints at (15,15) and + * (35,10), then rendered via `lv_draw_line` on a canvas layer. */ void lv_example_canvas_7(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_8.c b/examples/widgets/canvas/lv_example_canvas_8.c index 878ae0ced4..8e8f3b6181 100644 --- a/examples/widgets/canvas/lv_example_canvas_8.c +++ b/examples/widgets/canvas/lv_example_canvas_8.c @@ -7,7 +7,17 @@ #define CANVAS_HEIGHT 150 /** - * Draw a path to the canvas + * @title Vector path filled triangle + * @brief Build a closed three-point vector path and fill it blue on a canvas. + * + * A 150x150 `LV_COLOR_FORMAT_ARGB8888` canvas is centered with light + * grey background. An `lv_vector_path_t` at + * `LV_VECTOR_PATH_QUALITY_MEDIUM` is traced between (10,10), (130,130), + * and (10,130) using `lv_vector_path_move_to` and + * `lv_vector_path_line_to`, then closed. An `lv_draw_vector_dsc_t` + * with a blue fill color is attached to the path and rendered via + * `lv_draw_vector`. When vector graphics are disabled the example + * falls back to a centered "not enabled" label. */ void lv_example_canvas_8(void) { diff --git a/examples/widgets/canvas/lv_example_canvas_9.c b/examples/widgets/canvas/lv_example_canvas_9.c index d6769d3e47..53de73aa03 100644 --- a/examples/widgets/canvas/lv_example_canvas_9.c +++ b/examples/widgets/canvas/lv_example_canvas_9.c @@ -6,7 +6,14 @@ #define CANVAS_HEIGHT 150 /** - * Draw a triangle to the canvas + * @title Gradient triangle on canvas + * @brief Draw a triangle filled with a vertical red-to-transparent-blue gradient at 50% opacity. + * + * A 150x150 `LV_COLOR_FORMAT_ARGB8888` canvas is centered with a light + * grey background. An `lv_draw_triangle_dsc_t` is built with vertices + * at (10,10), (100,30), and (50,100), a `LV_GRAD_DIR_VER` gradient from + * red at `frac=64` to transparent blue at `frac=192`, and a top-level + * `opa` of 128, then rendered via `lv_draw_triangle` on a canvas layer. */ void lv_example_canvas_9(void) { diff --git a/examples/widgets/chart/about.md b/examples/widgets/chart/about.md new file mode 100644 index 0000000000..6451d62a64 --- /dev/null +++ b/examples/widgets/chart/about.md @@ -0,0 +1,4 @@ +--- +title: "Chart" +order: 50 +--- diff --git a/examples/widgets/chart/lv_example_chart_1.c b/examples/widgets/chart/lv_example_chart_1.c index 0d0838b714..0d5c382043 100644 --- a/examples/widgets/chart/lv_example_chart_1.c +++ b/examples/widgets/chart/lv_example_chart_1.c @@ -2,7 +2,15 @@ #if LV_USE_CHART && LV_BUILD_EXAMPLES /** - * A very basic line chart + * @title Basic line chart with two series + * @brief Line chart plotting one primary and one secondary Y-axis series with point drop shadows. + * + * A 200x150 chart is centered on the active screen with `LV_CHART_TYPE_LINE`. + * Two series are added: a green series bound to `LV_CHART_AXIS_PRIMARY_Y` + * filled with `lv_chart_set_next_value`, and a red series bound to + * `LV_CHART_AXIS_SECONDARY_Y` filled by writing directly into the Y array. + * Drop shadow styles on `LV_PART_ITEMS` give each point a glow and + * `lv_chart_refresh` commits the direct writes. */ void lv_example_chart_1(void) { diff --git a/examples/widgets/chart/lv_example_chart_2.c b/examples/widgets/chart/lv_example_chart_2.c index 447c1fa1a1..529eccffe9 100644 --- a/examples/widgets/chart/lv_example_chart_2.c +++ b/examples/widgets/chart/lv_example_chart_2.c @@ -2,7 +2,15 @@ #if LV_USE_CHART && LV_BUILD_EXAMPLES /** - * Use lv_scale to add ticks to a scrollable chart + * @title Scrollable bar chart with month scale + * @brief Bar chart inside a scrollable wrapper paired with a horizontal month scale. + * + * A 200x150 container holds a transparent flex-column wrapper sized to + * 300% width so the chart scrolls horizontally. The wrapper contains a + * `LV_CHART_TYPE_BAR` chart with 12 points and two green series, plus a + * `lv_scale` in `LV_SCALE_MODE_HORIZONTAL_BOTTOM` labeled with month + * abbreviations. The scale's horizontal padding is aligned to the first + * bar using `lv_chart_get_first_point_center_offset`. */ void lv_example_chart_2(void) { diff --git a/examples/widgets/chart/lv_example_chart_3.c b/examples/widgets/chart/lv_example_chart_3.c index 4e4458e75a..6f975bd6db 100644 --- a/examples/widgets/chart/lv_example_chart_3.c +++ b/examples/widgets/chart/lv_example_chart_3.c @@ -73,7 +73,16 @@ static void event_cb(lv_event_t * e) } /** - * Show the value of the pressed points + * @title Pressed point tooltip on stacked chart + * @brief Stacked bar chart that draws a value tooltip above the pressed point. + * + * A 280x180 `LV_CHART_TYPE_STACKED` chart holds three series (red, green, + * blue), each with 10 points. The chart subscribes to `LV_EVENT_ALL`: + * `LV_EVENT_REFR_EXT_DRAW_SIZE` reserves 20 px of external draw space, + * and `LV_EVENT_DRAW_POST_END` reads the pressed point via + * `lv_chart_get_pressed_point` and uses `lv_draw_rect` plus + * `lv_draw_label` to draw an accumulated dollar value above the stack. + * `LV_EVENT_VALUE_CHANGED` and `LV_EVENT_RELEASED` invalidate the chart. */ void lv_example_chart_3(void) { diff --git a/examples/widgets/chart/lv_example_chart_4.c b/examples/widgets/chart/lv_example_chart_4.c index 4583eef5aa..73c2c75ccf 100644 --- a/examples/widgets/chart/lv_example_chart_4.c +++ b/examples/widgets/chart/lv_example_chart_4.c @@ -23,7 +23,14 @@ static void draw_event_cb(lv_event_t * e) } /** - * Recolor the bars of a chart based on their value + * @title Value-based bar colors + * @brief Bar chart that tints each bar between green and red based on its value. + * + * A 260x160 `LV_CHART_TYPE_BAR` chart holds 24 points on one series. The + * chart sets `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` and subscribes to + * `LV_EVENT_DRAW_TASK_ADDED`. For each `LV_PART_ITEMS` fill task the + * callback reads the underlying Y value and replaces the fill color + * with an `lv_color_mix` of green and red proportional to the value. */ void lv_example_chart_4(void) { diff --git a/examples/widgets/chart/lv_example_chart_5.c b/examples/widgets/chart/lv_example_chart_5.c index 790a3e7011..1f91cb5a2f 100644 --- a/examples/widgets/chart/lv_example_chart_5.c +++ b/examples/widgets/chart/lv_example_chart_5.c @@ -8,7 +8,17 @@ static void add_faded_area(lv_event_t * e); static void draw_event_cb(lv_event_t * e); /** - * Add a faded area effect to the line chart and make some division lines ticker + * @title Faded area under line chart + * @brief Line chart with a vertical gradient fill beneath the line and styled division lines. + * + * A 200x150 `LV_CHART_TYPE_LINE` chart with 10 points uses + * `lv_chart_set_div_line_count` to draw 5 horizontal and 7 vertical + * division lines. With `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` enabled, the + * `LV_EVENT_DRAW_TASK_ADDED` callback intercepts `LV_PART_ITEMS` line + * tasks and fills each segment below the polyline with an + * `lv_draw_triangle` and `lv_draw_rect` pair using a vertical gradient + * in the series color. `LV_PART_MAIN` line tasks are recolored and + * dashed to highlight specific grid indices. */ void lv_example_chart_5(void) { diff --git a/examples/widgets/chart/lv_example_chart_6.c b/examples/widgets/chart/lv_example_chart_6.c index 23776d7923..bcaca49f3a 100644 --- a/examples/widgets/chart/lv_example_chart_6.c +++ b/examples/widgets/chart/lv_example_chart_6.c @@ -17,7 +17,15 @@ static void value_changed_event_cb(lv_event_t * e) } /** - * Show cursor on the clicked point + * @title Cursor follows clicked point + * @brief Line chart whose cursor snaps to the pressed data point. + * + * A 200x150 chart sits centered with one red series of 10 points and a + * blue cursor added via `lv_chart_add_cursor` with direction + * `LV_DIR_LEFT | LV_DIR_BOTTOM`. The `LV_EVENT_VALUE_CHANGED` callback + * reads `lv_chart_get_pressed_point` and moves the cursor with + * `lv_chart_set_cursor_point`. A prompt label reading "Click on a + * point" is aligned above the chart. */ void lv_example_chart_6(void) { diff --git a/examples/widgets/chart/lv_example_chart_7.c b/examples/widgets/chart/lv_example_chart_7.c index f05c0548b3..7e54249bb2 100644 --- a/examples/widgets/chart/lv_example_chart_7.c +++ b/examples/widgets/chart/lv_example_chart_7.c @@ -38,7 +38,17 @@ static void add_data(lv_timer_t * timer) } /** - * A scatter chart + * @title Scatter chart with fading points + * @brief Scatter chart whose points fade toward blue or red depending on their X and Y. + * + * A 200x150 `LV_CHART_TYPE_SCATTER` chart is configured with an X range + * of 0..200 and a Y range of 0..1000 and 50 points. Line width on + * `LV_PART_ITEMS` is zeroed so only the point markers show. With + * `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` set, the + * `LV_EVENT_DRAW_TASK_ADDED` callback fades older points by reducing + * opacity and recolors each `LV_PART_INDICATOR` fill between red and + * blue using the point's X and Y arrays. A 100 ms `lv_timer` pushes a + * new random point via `lv_chart_set_next_value2`. */ void lv_example_chart_7(void) { diff --git a/examples/widgets/chart/lv_example_chart_8.c b/examples/widgets/chart/lv_example_chart_8.c index b5fcf07e50..7eebf1d33d 100644 --- a/examples/widgets/chart/lv_example_chart_8.c +++ b/examples/widgets/chart/lv_example_chart_8.c @@ -20,7 +20,14 @@ static void add_data(lv_timer_t * t) } /** - * Circular line chart with gap + * @title Circular update mode with gap + * @brief Line chart that scrolls with `LV_CHART_UPDATE_MODE_CIRCULAR` and leaves a moving gap. + * + * A 280x150 line chart with 80 points and one red series is prefilled + * with random values, then a 300 ms `lv_timer` appends a new value via + * `lv_chart_set_next_value` and writes `LV_CHART_POINT_NONE` into the + * two slots ahead of the write cursor. The point indicator size is set + * to zero, producing a circular plot with a visible moving gap. */ void lv_example_chart_8(void) { diff --git a/examples/widgets/checkbox/about.md b/examples/widgets/checkbox/about.md new file mode 100644 index 0000000000..e5b80633ee --- /dev/null +++ b/examples/widgets/checkbox/about.md @@ -0,0 +1,4 @@ +--- +title: "Checkbox" +order: 55 +--- diff --git a/examples/widgets/checkbox/lv_example_checkbox_1.c b/examples/widgets/checkbox/lv_example_checkbox_1.c index 4fdd05965a..e544628ede 100644 --- a/examples/widgets/checkbox/lv_example_checkbox_1.c +++ b/examples/widgets/checkbox/lv_example_checkbox_1.c @@ -15,6 +15,17 @@ static void event_handler(lv_event_t * e) } } +/** + * @title Checkbox states stacked vertically + * @brief Four labelled checkboxes covering default, checked, disabled, and multi-line variants. + * + * The active screen uses `LV_FLEX_FLOW_COLUMN` with start alignment and holds + * four checkboxes: `Apple` in the default state, `Banana` with + * `LV_STATE_CHECKED`, `Lemon` with `LV_STATE_DISABLED`, and + * `Melon\nand a new line` with both checked and disabled states and a + * two-line label. A shared `LV_EVENT_ALL` callback logs the checkbox text + * and its current checked state on `LV_EVENT_VALUE_CHANGED`. + */ void lv_example_checkbox_1(void) { lv_obj_set_flex_flow(lv_screen_active(), LV_FLEX_FLOW_COLUMN); diff --git a/examples/widgets/checkbox/lv_example_checkbox_2.c b/examples/widgets/checkbox/lv_example_checkbox_2.c index f8f77e5263..78a9a0fefc 100644 --- a/examples/widgets/checkbox/lv_example_checkbox_2.c +++ b/examples/widgets/checkbox/lv_example_checkbox_2.c @@ -16,7 +16,16 @@ static void event_cb(lv_event_t * e) } /** - * Checkboxes as radio buttons + * @title Checkboxes as radio buttons + * @brief A group of five checkboxes where only one can be checked at a time. + * + * A centered flex-column container holds five checkboxes labelled + * `Radio button 1` through `Radio button 5`. Each one calls + * `lv_obj_set_radio_button(obj, true)` so checking one clears the others, + * and two `LV_PART_INDICATOR` styles round the indicator with + * `LV_RADIUS_CIRCLE` and clear the default checkmark image in + * `LV_STATE_CHECKED`. Each checkbox logs its label and selection state on + * `LV_EVENT_VALUE_CHANGED`. */ void lv_example_checkbox_2(void) { diff --git a/examples/widgets/dropdown/about.md b/examples/widgets/dropdown/about.md new file mode 100644 index 0000000000..ed1216cbe8 --- /dev/null +++ b/examples/widgets/dropdown/about.md @@ -0,0 +1,4 @@ +--- +title: "Dropdown" +order: 60 +--- diff --git a/examples/widgets/dropdown/lv_example_dropdown_1.c b/examples/widgets/dropdown/lv_example_dropdown_1.c index 8e794f948b..f6aa500842 100644 --- a/examples/widgets/dropdown/lv_example_dropdown_1.c +++ b/examples/widgets/dropdown/lv_example_dropdown_1.c @@ -12,6 +12,15 @@ static void event_handler(lv_event_t * e) } } +/** + * @title Basic dropdown with event log + * @brief A dropdown of fruit names logs the picked option on change. + * + * A single dropdown anchored to `LV_ALIGN_TOP_MID` is filled with a newline + * separated list of ten fruits via `lv_dropdown_set_options`. An `LV_EVENT_ALL` + * handler reacts to `LV_EVENT_VALUE_CHANGED` by copying the current selection + * with `lv_dropdown_get_selected_str` and printing it through `LV_LOG_USER`. + */ void lv_example_dropdown_1(void) { diff --git a/examples/widgets/dropdown/lv_example_dropdown_2.c b/examples/widgets/dropdown/lv_example_dropdown_2.c index 10c485a046..88c773f611 100644 --- a/examples/widgets/dropdown/lv_example_dropdown_2.c +++ b/examples/widgets/dropdown/lv_example_dropdown_2.c @@ -2,7 +2,15 @@ #if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES /** - * Create a drop down, up, left and right menus + * @title Dropdowns opening in four directions + * @brief Four dropdowns share a menu and open toward top, bottom, left, and right. + * + * Four dropdowns built from the same `Apple/Banana/Orange/Melon` option string + * are anchored to the top, bottom, left, and right of the screen. Each one + * sets its open direction through `lv_dropdown_set_dir` (`LV_DIR_BOTTOM`, + * `LV_DIR_RIGHT`, `LV_DIR_LEFT`) and picks a matching arrow via + * `lv_dropdown_set_symbol` (`LV_SYMBOL_UP`, `LV_SYMBOL_RIGHT`, + * `LV_SYMBOL_LEFT`). The top dropdown keeps the default downward open. */ void lv_example_dropdown_2(void) { diff --git a/examples/widgets/dropdown/lv_example_dropdown_3.c b/examples/widgets/dropdown/lv_example_dropdown_3.c index 5bb40e6101..f76a4e71f6 100644 --- a/examples/widgets/dropdown/lv_example_dropdown_3.c +++ b/examples/widgets/dropdown/lv_example_dropdown_3.c @@ -10,7 +10,16 @@ static void event_cb(lv_event_t * e) } /** - * Create a menu from a drop-down list and show some drop-down list features and styling + * @title Dropdown styled as a menu + * @brief Turn a dropdown into a fixed-label menu with a rotating caret image. + * + * A dropdown in the top-left is filled with file-menu actions and given a + * fixed button label of `Menu` via `lv_dropdown_set_text`. `img_caret_down` is + * installed with `lv_dropdown_set_symbol` and rotated 180 degrees on + * `LV_PART_INDICATOR | LV_STATE_CHECKED` using `transform_rotation` so the + * caret flips when the list opens. `lv_dropdown_set_selected_highlight(false)` + * drops the last-picked highlight, and an `LV_EVENT_VALUE_CHANGED` handler + * logs the chosen item. */ void lv_example_dropdown_3(void) { diff --git a/examples/widgets/image/about.md b/examples/widgets/image/about.md new file mode 100644 index 0000000000..3268e89049 --- /dev/null +++ b/examples/widgets/image/about.md @@ -0,0 +1,4 @@ +--- +title: "Image" +order: 65 +--- diff --git a/examples/widgets/image/lv_example_image_1.c b/examples/widgets/image/lv_example_image_1.c index 0e2bd55e10..68e5413a8a 100644 --- a/examples/widgets/image/lv_example_image_1.c +++ b/examples/widgets/image/lv_example_image_1.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_USE_IMAGE && LV_BUILD_EXAMPLES +/** + * @title Image from C array and symbol text + * @brief Show a compiled-in cogwheel bitmap next to a text label rendered from a symbol font. + * + * Two `lv_image` widgets are placed on the active screen. The first + * calls `lv_image_set_src` with the `img_cogwheel_argb` descriptor + * declared through `LV_IMAGE_DECLARE` and is centered. The second + * points at the string `LV_SYMBOL_OK "Accept"` and is aligned below + * the first with `LV_ALIGN_OUT_BOTTOM_MID` and a 20 px offset. + */ void lv_example_image_1(void) { LV_IMAGE_DECLARE(img_cogwheel_argb); diff --git a/examples/widgets/image/lv_example_image_2.c b/examples/widgets/image/lv_example_image_2.c index 2b5cb2df4a..5a0aa8b503 100644 --- a/examples/widgets/image/lv_example_image_2.c +++ b/examples/widgets/image/lv_example_image_2.c @@ -8,7 +8,15 @@ static lv_obj_t * red_slider, * green_slider, * blue_slider, * intense_slider; static lv_obj_t * img1; /** - * Demonstrate runtime image re-coloring + * @title Image recolor with RGB sliders + * @brief Four sliders drive the recolor tint and intensity of a cogwheel image. + * + * Red, green, blue, and intensity sliders (range 0 to 255) sit along + * the left half of the screen while the `img_cogwheel_argb` image sits + * on the right. A shared `LV_EVENT_VALUE_CHANGED` callback reads each + * slider and applies `lv_obj_set_style_image_recolor` and + * `lv_obj_set_style_image_recolor_opa` so the image retints live as + * the sliders move. */ void lv_example_image_2(void) { diff --git a/examples/widgets/image/lv_example_image_3.c b/examples/widgets/image/lv_example_image_3.c index 9879559e3e..ec231a2039 100644 --- a/examples/widgets/image/lv_example_image_3.c +++ b/examples/widgets/image/lv_example_image_3.c @@ -12,7 +12,15 @@ static void set_scale(void * img, int32_t v) } /** - * Show transformations (zoom and rotation) using a pivot point. + * @title Rotate and zoom around a pivot + * @brief Spin and scale a cogwheel image continuously around its top-left corner. + * + * `lv_image_set_pivot` moves the transform origin to (0, 0) so the + * image rotates around its top-left corner. One `lv_anim_t` drives + * `lv_image_set_rotation` from 0 to 3600 over 5000 ms and repeats + * forever with `LV_ANIM_REPEAT_INFINITE`. A second animation drives + * `lv_image_set_scale` from 128 to 256 with a 3000 ms reverse phase + * so the image pulses while spinning. */ void lv_example_image_3(void) { diff --git a/examples/widgets/image/lv_example_image_4.c b/examples/widgets/image/lv_example_image_4.c index 7ec2553132..b6b2f5095e 100644 --- a/examples/widgets/image/lv_example_image_4.c +++ b/examples/widgets/image/lv_example_image_4.c @@ -7,7 +7,15 @@ static void ofs_y_anim(void * img, int32_t v) } /** - * Image styling and offset + * @title Image styling and vertical offset + * @brief Scroll the pixels of a recolored, yellow-backed strip image vertically. + * + * An `lv_style_t` with a yellow background and a black recolor at + * `LV_OPA_COVER` is applied to an image that uses the + * `img_skew_strip` source and is clipped to 150x100. An infinite + * `lv_anim_t` drives `lv_image_set_offset_y` from 0 to 100 over + * 3000 ms with a 500 ms reverse phase, so the visible pixels scroll + * up and back down inside the fixed frame. */ void lv_example_image_4(void) { diff --git a/examples/widgets/image/lv_example_image_5.c b/examples/widgets/image/lv_example_image_5.c index a0399b4fd0..6ec2c40f4a 100644 --- a/examples/widgets/image/lv_example_image_5.c +++ b/examples/widgets/image/lv_example_image_5.c @@ -1,6 +1,18 @@ #include "../../lv_examples.h" #if LV_USE_IMAGE && LV_BUILD_EXAMPLES +/** + * @title SVG image with transform style + * @brief Display an SVG source scaled and rotated via both widget and style APIs. + * + * An `lv_image` loaded from the `img_svg_img` descriptor is sized to + * 100% width and 50% height and given a 5 px outline. Rotation is set + * to 450 (45 degrees) and scale to 128 twice, once through + * `lv_obj_set_style_transform_rotation` and + * `lv_obj_set_style_transform_scale` and once through + * `lv_image_set_rotation` and `lv_image_set_scale`, then the image is + * centered. + */ void lv_example_image_5(void) { LV_IMAGE_DECLARE(img_svg_img); diff --git a/examples/widgets/imagebutton/about.md b/examples/widgets/imagebutton/about.md new file mode 100644 index 0000000000..0c1a8c355c --- /dev/null +++ b/examples/widgets/imagebutton/about.md @@ -0,0 +1,6 @@ +--- +title: "Image Button" +order: 70 +--- + +A button whose background is composed from left, center, and right image slices, letting it stretch to any width without distortion. diff --git a/examples/widgets/imagebutton/lv_example_imagebutton_1.c b/examples/widgets/imagebutton/lv_example_imagebutton_1.c index 22fd694fce..2217f39617 100644 --- a/examples/widgets/imagebutton/lv_example_imagebutton_1.c +++ b/examples/widgets/imagebutton/lv_example_imagebutton_1.c @@ -1,6 +1,19 @@ #include "../../lv_examples.h" #if LV_USE_IMAGEBUTTON && LV_BUILD_EXAMPLES +/** + * @title Image button with press transition + * @brief Three-part image button that widens and darkens while pressed. + * + * An `lv_imagebutton` uses `imagebutton_left`, `imagebutton_mid`, and + * `imagebutton_right` for the `LV_IMAGEBUTTON_STATE_RELEASED` source + * so the middle piece stretches across a fixed width of 100. A style + * transition on `LV_STYLE_TRANSFORM_WIDTH` and + * `LV_STYLE_IMAGE_RECOLOR_OPA` runs `lv_anim_path_linear` over 200 ms + * when `LV_STATE_PRESSED` is entered, widening the button by 20 px + * and darkening it with a black recolor at `LV_OPA_30`. A centered + * label reads `Button`. + */ void lv_example_imagebutton_1(void) { LV_IMAGE_DECLARE(imagebutton_left); diff --git a/examples/widgets/keyboard/about.md b/examples/widgets/keyboard/about.md new file mode 100644 index 0000000000..d26bbef433 --- /dev/null +++ b/examples/widgets/keyboard/about.md @@ -0,0 +1,4 @@ +--- +title: "Keyboard" +order: 75 +--- diff --git a/examples/widgets/keyboard/lv_example_keyboard_1.c b/examples/widgets/keyboard/lv_example_keyboard_1.c index 7a2bbb3f39..58d89ed964 100644 --- a/examples/widgets/keyboard/lv_example_keyboard_1.c +++ b/examples/widgets/keyboard/lv_example_keyboard_1.c @@ -17,6 +17,16 @@ static void ta_event_cb(lv_event_t * e) } } +/** + * @title Keyboard shown on textarea focus + * @brief Hide the keyboard unless one of two textareas is focused. + * + * Two textareas are placed at the top-left and top-right, one with placeholder + * text `Hello`. A shared callback watches `LV_EVENT_FOCUSED` and + * `LV_EVENT_DEFOCUSED`: on focus it retargets the keyboard with + * `lv_keyboard_set_textarea` and clears `LV_OBJ_FLAG_HIDDEN`, and on defocus it + * clears the target and hides the keyboard again. + */ void lv_example_keyboard_1(void) { /*Create a keyboard to use it with an of the text areas*/ diff --git a/examples/widgets/keyboard/lv_example_keyboard_2.c b/examples/widgets/keyboard/lv_example_keyboard_2.c index a63df2f6f0..847a7a2966 100644 --- a/examples/widgets/keyboard/lv_example_keyboard_2.c +++ b/examples/widgets/keyboard/lv_example_keyboard_2.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_USE_KEYBOARD && LV_BUILD_EXAMPLES +/** + * @title AZERTY layout as USER_1 mode + * @brief Register a custom AZERTY button map on the keyboard. + * + * A `kb_map` and matching `lv_buttonmatrix_ctrl_t` control array describe an + * AZERTY layout with `LV_SYMBOL_BACKSPACE`, `LV_SYMBOL_NEW_LINE`, + * `LV_SYMBOL_CLOSE`, and `LV_SYMBOL_OK`. `lv_keyboard_set_map` installs the + * layout under `LV_KEYBOARD_MODE_USER_1` and `lv_keyboard_set_mode` activates + * it. A focused textarea above the keyboard receives the typed characters. + */ void lv_example_keyboard_2(void) { /*Create an AZERTY keyboard map*/ diff --git a/examples/widgets/keyboard/lv_example_keyboard_3.c b/examples/widgets/keyboard/lv_example_keyboard_3.c index 1899a32329..37fe93fda8 100644 --- a/examples/widgets/keyboard/lv_example_keyboard_3.c +++ b/examples/widgets/keyboard/lv_example_keyboard_3.c @@ -51,7 +51,15 @@ static void event_cb(lv_event_t * e) } /** - * Add custom drawer to the keyboard to customize the buttons one by one + * @title Per-button colors via draw task hook + * @brief Recolor each keyboard key and swap the OK symbol for a star image. + * + * A centered `lv_keyboard` has `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` set and a + * `LV_EVENT_DRAW_TASK_ADDED` callback attached. For every `LV_PART_ITEMS` draw + * task the handler picks a palette entry from `base_dsc->id1`, darkens it while + * the button is in `LV_STATE_PRESSED`, and lightens the label text. When the + * task is drawing `LV_SYMBOL_OK` the label is hidden and `img_star` is drawn in + * its place. */ void lv_example_keyboard_3(void) { diff --git a/examples/widgets/label/about.md b/examples/widgets/label/about.md new file mode 100644 index 0000000000..cda6ad1d42 --- /dev/null +++ b/examples/widgets/label/about.md @@ -0,0 +1,4 @@ +--- +title: "Label" +order: 80 +--- diff --git a/examples/widgets/label/lv_example_label_1.c b/examples/widgets/label/lv_example_label_1.c index fa2fb5d701..566d65cb32 100644 --- a/examples/widgets/label/lv_example_label_1.c +++ b/examples/widgets/label/lv_example_label_1.c @@ -2,7 +2,14 @@ #if LV_USE_LABEL && LV_BUILD_EXAMPLES /** - * Show line wrap, re-color, line align and text scrolling. + * @title Wrapping and circular scrolling labels + * @brief Two labels share a width, one wraps with inline recolor and one scrolls in a loop. + * + * The top label sets `LV_LABEL_LONG_MODE_WRAP`, enables recolor so `#RRGGBB text#` + * markers change color per word, fixes the width to 150 px, and center-aligns text + * with `LV_TEXT_ALIGN_CENTER`. The bottom label uses + * `LV_LABEL_LONG_MODE_SCROLL_CIRCULAR` with the same width so its text cycles + * through continuously. */ void lv_example_label_1(void) { diff --git a/examples/widgets/label/lv_example_label_2.c b/examples/widgets/label/lv_example_label_2.c index c85a7b8640..49f6145dd0 100644 --- a/examples/widgets/label/lv_example_label_2.c +++ b/examples/widgets/label/lv_example_label_2.c @@ -2,7 +2,13 @@ #if LV_USE_LABEL && LV_BUILD_EXAMPLES /** - * Create a fake text shadow + * @title Faux text shadow from two labels + * @brief Layer two labels with the same text to fake a drop shadow. + * + * A background label receives a style that sets `text_opa` to `LV_OPA_30` and a + * black `text_color`, then the same text is placed on a foreground label centered + * on the screen. The shadow label is aligned to the main label's top-left with a + * 2 px x/y offset via `lv_obj_align_to`. */ void lv_example_label_2(void) { diff --git a/examples/widgets/label/lv_example_label_3.c b/examples/widgets/label/lv_example_label_3.c index b9e4475404..2e9dee69a8 100644 --- a/examples/widgets/label/lv_example_label_3.c +++ b/examples/widgets/label/lv_example_label_3.c @@ -2,7 +2,14 @@ #if LV_USE_LABEL && LV_BUILD_EXAMPLES && LV_FONT_DEJAVU_16_PERSIAN_HEBREW && LV_FONT_SOURCE_HAN_SANS_SC_16_CJK && LV_USE_BIDI /** - * Show mixed LTR, RTL and Chinese label + * @title LTR, RTL, and CJK labels + * @brief Three labels rendered with scripts that need different fonts and base directions. + * + * An English label at the top-left uses `lv_font_montserrat_16`. A Hebrew label + * in the middle sets `base_dir` to `LV_BASE_DIR_RTL` and renders with + * `lv_font_dejavu_16_persian_hebrew`. A Simplified Chinese label at the + * bottom-left renders with `lv_font_source_han_sans_sc_16_cjk`. All three wrap at + * 310 px. */ void lv_example_label_3(void) { diff --git a/examples/widgets/label/lv_example_label_4.c b/examples/widgets/label/lv_example_label_4.c index 89d93255ed..c699698eaa 100644 --- a/examples/widgets/label/lv_example_label_4.c +++ b/examples/widgets/label/lv_example_label_4.c @@ -31,7 +31,14 @@ static void generate_mask(lv_draw_buf_t * mask, int32_t w, int32_t h, const char } /** - * Draw label with gradient color + * @title Gradient-filled text via bitmap mask + * @brief Render text with a gradient fill by masking a gradient rectangle. + * + * A canvas in `LV_COLOR_FORMAT_L8` is used as an alpha mask: a centered label is + * drawn onto it with `lv_draw_label` using `lv_font_montserrat_24`. A plain + * object sized 150x60 is created, given a horizontal red-to-blue background + * gradient with `LV_GRAD_DIR_HOR`, and the mask is applied through + * `lv_obj_set_style_bitmap_mask_src` so only the text shape shows through. */ void lv_example_label_4(void) { diff --git a/examples/widgets/label/lv_example_label_5.c b/examples/widgets/label/lv_example_label_5.c index 46b5740e97..0c635e551b 100644 --- a/examples/widgets/label/lv_example_label_5.c +++ b/examples/widgets/label/lv_example_label_5.c @@ -2,8 +2,14 @@ #if LV_USE_LABEL && LV_BUILD_EXAMPLES /** - * Show customizing the circular scrolling animation of a label with `LV_LABEL_LONG_MODE_SCROLL_CIRCULAR` - * long mode. + * @title Customized circular scroll timing + * @brief Set delays and infinite repeats on a label's circular scroll animation. + * + * An `lv_anim_t` template is configured with a 1000 ms initial delay, a 3000 ms + * repeat delay, and `LV_ANIM_REPEAT_INFINITE`. A style stores the template via + * `lv_style_set_anim` and is attached to a 150 px wide label running in + * `LV_LABEL_LONG_MODE_SCROLL_CIRCULAR`, which applies the timing whenever the + * scroll animation fires. */ void lv_example_label_5(void) { diff --git a/examples/widgets/label/lv_example_label_6.c b/examples/widgets/label/lv_example_label_6.c index fbd662be08..02d1b05c29 100644 --- a/examples/widgets/label/lv_example_label_6.c +++ b/examples/widgets/label/lv_example_label_6.c @@ -13,6 +13,16 @@ static bool fix_w_get_glyph_dsc(const lv_font_t * font, lv_font_glyph_dsc_t * ds return true; } +/** + * @title Monospace font via glyph override + * @brief Clone a proportional font and force fixed advance width on each glyph. + * + * A copy of `lv_font_montserrat_20` is made and its `get_glyph_dsc` callback is + * replaced with a helper that sets `adv_w` to 20 and recenters `ofs_x` for every + * glyph. Two labels render the string `0123.Wabc`: the first with the original + * proportional font, the second with the patched monospace clone so column + * alignment becomes visible. + */ void lv_example_label_6(void) { /* Clone the original font and override its behavior */ diff --git a/examples/widgets/label/lv_example_label_7.c b/examples/widgets/label/lv_example_label_7.c index 16c079638a..2837fd5922 100644 --- a/examples/widgets/label/lv_example_label_7.c +++ b/examples/widgets/label/lv_example_label_7.c @@ -28,7 +28,15 @@ static void language_change_cb(lv_event_t * e) } /** - * Use a translation tag in labels + * @title Label translation tags with dropdown + * @brief Switch label text between English, German, and Spanish from a dropdown. + * + * A static translation table keyed by the tags `tiger`, `lion`, `rabbit`, and + * `elephant` is registered with `lv_translation_add_static`. A dropdown lists + * the three languages and its `LV_EVENT_VALUE_CHANGED` handler calls + * `lv_translation_set_language` with the selected string. One label per tag is + * created with `lv_label_set_translation_tag`, and all labels refresh to the + * chosen language. */ void lv_example_label_7(void) { diff --git a/examples/widgets/led/about.md b/examples/widgets/led/about.md new file mode 100644 index 0000000000..6a4acdedc9 --- /dev/null +++ b/examples/widgets/led/about.md @@ -0,0 +1,6 @@ +--- +title: "LED" +order: 85 +--- + +A rendered indicator drawn as a glowing rectangle, controlled via `lv_led_on`, `lv_led_off`, and `lv_led_set_brightness`. Not tied to hardware. diff --git a/examples/widgets/led/lv_example_led_1.c b/examples/widgets/led/lv_example_led_1.c index 2e7ad93eaa..917b9b88df 100644 --- a/examples/widgets/led/lv_example_led_1.c +++ b/examples/widgets/led/lv_example_led_1.c @@ -2,7 +2,14 @@ #if LV_USE_LED && LV_BUILD_EXAMPLES /** - * Create LED's with different brightness and color + * @title Three LEDs at different brightness + * @brief One LED off, one dimmed red at mid brightness, and one fully on. + * + * Three `lv_led` objects are placed left of centre, at centre, and + * right of centre. The first is turned off with `lv_led_off`, the + * second is tinted red via `lv_led_set_color` and dimmed to + * brightness 150 with `lv_led_set_brightness`, and the third is + * switched on with `lv_led_on`. */ void lv_example_led_1(void) { diff --git a/examples/widgets/line/about.md b/examples/widgets/line/about.md new file mode 100644 index 0000000000..7e16ebc12e --- /dev/null +++ b/examples/widgets/line/about.md @@ -0,0 +1,4 @@ +--- +title: "Line" +order: 90 +--- diff --git a/examples/widgets/line/lv_example_line_1.c b/examples/widgets/line/lv_example_line_1.c index d2dc6bb8e0..f630bee224 100644 --- a/examples/widgets/line/lv_example_line_1.c +++ b/examples/widgets/line/lv_example_line_1.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_USE_LINE && LV_BUILD_EXAMPLES +/** + * @title Styled polyline through five points + * @brief Draw a rounded blue polyline through five fixed coordinates. + * + * A static array of five `lv_point_precise_t` coordinates defines the + * polyline. An `lv_style_t` sets `line_width` to 8, `line_color` to + * `lv_palette_main(LV_PALETTE_BLUE)`, and `line_rounded` to true. + * `lv_line_create` and `lv_line_set_points` build the shape on the + * active screen, the style is attached, and the line is centered. + */ void lv_example_line_1(void) { /*Create an array for the points of the line*/ diff --git a/examples/widgets/list/about.md b/examples/widgets/list/about.md new file mode 100644 index 0000000000..177260096c --- /dev/null +++ b/examples/widgets/list/about.md @@ -0,0 +1,4 @@ +--- +title: "List" +order: 95 +--- diff --git a/examples/widgets/list/lv_example_list_1.c b/examples/widgets/list/lv_example_list_1.c index 7b8d53b348..529e94f118 100644 --- a/examples/widgets/list/lv_example_list_1.c +++ b/examples/widgets/list/lv_example_list_1.c @@ -11,6 +11,17 @@ static void event_handler(lv_event_t * e) LV_LOG_USER("Clicked: %s", lv_list_get_button_text(list1, obj)); } } + +/** + * @title Icon list with section headers + * @brief A 180x220 list grouped into File, Connectivity, and Exit sections with symbol icons. + * + * `lv_list_create` builds a centered list; `lv_list_add_text` inserts + * section headers and `lv_list_add_button` adds entries such as + * `LV_SYMBOL_FILE` + "New" or `LV_SYMBOL_BLUETOOTH` + "Bluetooth". A + * single `LV_EVENT_CLICKED` handler logs the clicked entry via + * `lv_list_get_button_text`. + */ void lv_example_list_1(void) { /*Create a list*/ diff --git a/examples/widgets/list/lv_example_list_2.c b/examples/widgets/list/lv_example_list_2.c index 9ace1d26f1..6993835efc 100644 --- a/examples/widgets/list/lv_example_list_2.c +++ b/examples/widgets/list/lv_example_list_2.c @@ -107,6 +107,19 @@ static void event_handler_swap(lv_event_t * e) } } +/** + * @title Reorderable list with control panel + * @brief Select a row in one list and move it with Top, Up, Center, Down, Bottom, or Shuffle. + * + * A 60% wide list on the left holds 15 `lv_button` rows labeled + * `Item 0` through `Item 14`; clicking a row marks it as the current + * selection with `LV_STATE_CHECKED` and clears the state on siblings. + * A 40% wide list on the right pins Top, Up, Center, Down, Bottom, + * and Shuffle buttons wired to `LV_EVENT_ALL` handlers that call + * `lv_obj_move_to_index` and `lv_obj_scroll_to_view` to reposition + * the selected row, with the Up, Center, Down, and Shuffle handlers + * also firing on `LV_EVENT_LONG_PRESSED_REPEAT`. + */ void lv_example_list_2(void) { /*Create a list*/ diff --git a/examples/widgets/lottie/about.md b/examples/widgets/lottie/about.md new file mode 100644 index 0000000000..ab18d90029 --- /dev/null +++ b/examples/widgets/lottie/about.md @@ -0,0 +1,4 @@ +--- +title: "Lottie" +order: 100 +--- diff --git a/examples/widgets/lottie/lv_example_lottie_1.c b/examples/widgets/lottie/lv_example_lottie_1.c index fa4067ea37..2da1488460 100644 --- a/examples/widgets/lottie/lv_example_lottie_1.c +++ b/examples/widgets/lottie/lv_example_lottie_1.c @@ -3,7 +3,16 @@ #if LV_USE_LOTTIE /** - * Load an lottie animation from data + * @title Lottie animation from memory + * @brief Play a Lottie JSON animation embedded as a C byte array. + * + * An `lv_lottie` widget on the active screen receives the approve + * animation through `lv_lottie_set_src_data`, pointing at the + * `lv_example_lottie_approve` byte array and its size. A 64x64 + * ARGB8888 premultiplied buffer is attached with + * `lv_lottie_set_buffer` when the draw buffer alignment allows, or an + * `LV_DRAW_BUF_DEFINE_STATIC` draw buffer via `lv_lottie_set_draw_buf` + * otherwise, then the widget is centered. */ void lv_example_lottie_1(void) { diff --git a/examples/widgets/lottie/lv_example_lottie_2.c b/examples/widgets/lottie/lv_example_lottie_2.c index ad91c08c6c..8f3319d477 100644 --- a/examples/widgets/lottie/lv_example_lottie_2.c +++ b/examples/widgets/lottie/lv_example_lottie_2.c @@ -3,7 +3,16 @@ #if LV_USE_LOTTIE /** - * Load an lottie animation from file + * @title Lottie animation from file path + * @brief Play a Lottie JSON animation loaded through the filesystem driver. + * + * An `lv_lottie` widget is created on the active screen and receives + * its source through `lv_lottie_set_src_file`, pointing at + * `lvgl/examples/widgets/lottie/lv_example_lottie_approve.json`, so a + * filesystem driver for the working directory must be registered. A + * 64x64 ARGB8888 premultiplied buffer is attached via + * `lv_lottie_set_buffer` or `lv_lottie_set_draw_buf` depending on the + * draw buffer alignment, then the widget is centered. */ void lv_example_lottie_2(void) { diff --git a/examples/widgets/menu/about.md b/examples/widgets/menu/about.md new file mode 100644 index 0000000000..2d30db4bf4 --- /dev/null +++ b/examples/widgets/menu/about.md @@ -0,0 +1,4 @@ +--- +title: "Menu" +order: 105 +--- diff --git a/examples/widgets/menu/lv_example_menu_1.c b/examples/widgets/menu/lv_example_menu_1.c index 7edbcae789..2c2d21e40a 100644 --- a/examples/widgets/menu/lv_example_menu_1.c +++ b/examples/widgets/menu/lv_example_menu_1.c @@ -1,6 +1,17 @@ #include "../../lv_examples.h" #if LV_USE_MENU && LV_BUILD_EXAMPLES +/** + * @title Basic menu with sub page + * @brief A three-item main page whose third entry opens a hidden sub page. + * + * A display-sized `lv_menu` holds a main page with three + * `lv_menu_cont` items labeled `Item 1`, `Item 2`, and + * `Item 3 (Click me!)`. A separate sub page created with + * `lv_menu_page_create` carries a greeting label, and + * `lv_menu_set_load_page_event` wires the third item to load that sub + * page when clicked. `lv_menu_set_page` opens the main page. + */ void lv_example_menu_1(void) { /*Create a menu object*/ diff --git a/examples/widgets/menu/lv_example_menu_2.c b/examples/widgets/menu/lv_example_menu_2.c index 31e000940b..95492614fd 100644 --- a/examples/widgets/menu/lv_example_menu_2.c +++ b/examples/widgets/menu/lv_example_menu_2.c @@ -14,6 +14,19 @@ static void back_event_handler(lv_event_t * e) } } +/** + * @title Menu with root back button + * @brief A menu whose always-visible root back button pops a message box when tapped. + * + * `lv_menu_set_mode_root_back_button` turns on + * `LV_MENU_ROOT_BACK_BUTTON_ENABLED` so the back button remains on + * the header at the top of the navigation stack. The main page holds + * three items and the third opens a sub page through + * `lv_menu_set_load_page_event`. A `LV_EVENT_CLICKED` handler calls + * `lv_menu_back_button_is_root` and, when true, creates an + * `lv_msgbox` with title `Hello`, text `Root back btn click.`, and a + * close button. + */ void lv_example_menu_2(void) { lv_obj_t * menu = lv_menu_create(lv_screen_active()); diff --git a/examples/widgets/menu/lv_example_menu_3.c b/examples/widgets/menu/lv_example_menu_3.c index f4210a89e9..0a3314a365 100644 --- a/examples/widgets/menu/lv_example_menu_3.c +++ b/examples/widgets/menu/lv_example_menu_3.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_USE_MENU && LV_BUILD_EXAMPLES +/** + * @title Customized back button header + * @brief A menu with a labeled "Back" button in the header and three titled sub pages. + * + * `lv_menu_get_main_header_back_button` returns the default back + * button, and a child `lv_label` adds the text `Back` next to its + * icon. The main page lists three items, each wired with + * `lv_menu_set_load_page_event` to sub pages titled `Page 1` through + * `Page 3` created via `lv_menu_page_create`. + */ void lv_example_menu_3(void) { /*Create a menu object*/ diff --git a/examples/widgets/menu/lv_example_menu_4.c b/examples/widgets/menu/lv_example_menu_4.c index 1249f36d2c..24925da0f9 100644 --- a/examples/widgets/menu/lv_example_menu_4.c +++ b/examples/widgets/menu/lv_example_menu_4.c @@ -28,6 +28,19 @@ static void float_button_event_cb(lv_event_t * e) lv_obj_scroll_to_view_recursive(cont, LV_ANIM_ON); } +/** + * @title Menu with floating add button + * @brief A circular floating button appends new items and matching sub pages. + * + * The menu starts with a single main-page item wired to a greeting + * sub page. A circular `lv_button` flagged with + * `LV_OBJ_FLAG_FLOATING` is anchored to the bottom-right corner with + * a plus symbol background and a large theme font. Its + * `LV_EVENT_CLICKED` handler increments a counter, creates a new sub + * page and a new main-page row labeled `Item N`, links them with + * `lv_menu_set_load_page_event`, and calls + * `lv_obj_scroll_to_view_recursive` so the fresh row stays visible. + */ void lv_example_menu_4(void) { /*Create a menu object*/ diff --git a/examples/widgets/menu/lv_example_menu_5.c b/examples/widgets/menu/lv_example_menu_5.c index c8057ed086..2d2f9d88fb 100644 --- a/examples/widgets/menu/lv_example_menu_5.c +++ b/examples/widgets/menu/lv_example_menu_5.c @@ -16,6 +16,21 @@ static lv_obj_t * create_slider(lv_obj_t * parent, static lv_obj_t * create_switch(lv_obj_t * parent, const char * icon, const char * txt, bool chk); +/** + * @title Settings menu with sidebar mode + * @brief A full Settings screen with sidebar navigation and a switch that toggles between sidebar and stacked modes. + * + * A root page named `Settings` lists Mechanics, Sound, Display, and + * About entries inside `lv_menu_section` groups, with a Menu mode row + * that holds a `lv_switch` to flip between sidebar and stacked + * navigation through `lv_menu_set_sidebar_page` or + * `lv_menu_set_page`. Sub pages build slider rows such as + * `Velocity 0..150 at 120` and a sound switch using helper builders + * that pair a label with an `lv_slider` or `lv_switch`. The root + * back button is enabled and a `LV_EVENT_CLICKED` handler on the menu + * pops an `lv_msgbox` saying `Root back btn click.` when the root + * back arrow is used. + */ void lv_example_menu_5(void) { lv_obj_t * menu = lv_menu_create(lv_screen_active()); diff --git a/examples/widgets/msgbox/about.md b/examples/widgets/msgbox/about.md new file mode 100644 index 0000000000..7a96c6a18b --- /dev/null +++ b/examples/widgets/msgbox/about.md @@ -0,0 +1,6 @@ +--- +title: "Message Box" +order: 110 +--- + +Modal dialog created with `lv_msgbox_create` that displays a title, text, and action buttons. diff --git a/examples/widgets/msgbox/lv_example_msgbox_1.c b/examples/widgets/msgbox/lv_example_msgbox_1.c index 6f388f1468..296cfa9b49 100644 --- a/examples/widgets/msgbox/lv_example_msgbox_1.c +++ b/examples/widgets/msgbox/lv_example_msgbox_1.c @@ -9,6 +9,18 @@ static void event_cb(lv_event_t * e) LV_LOG_USER("Button %s clicked", lv_label_get_text(label)); } +/** + * @title Modal message box with footer buttons + * @brief A modal "Hello" dialog with Apply and Cancel footer buttons and a close icon. + * + * `lv_msgbox_create(NULL)` opens a modal message box on the top + * layer. `lv_msgbox_add_title` sets the title to `Hello`, + * `lv_msgbox_add_text` writes the body, and + * `lv_msgbox_add_close_button` installs the header close icon. Two + * `lv_msgbox_add_footer_button` calls add `Apply` and `Cancel`, each + * wired to a shared `LV_EVENT_CLICKED` handler that logs which label + * was tapped. + */ void lv_example_msgbox_1(void) { lv_obj_t * mbox1 = lv_msgbox_create(NULL); diff --git a/examples/widgets/msgbox/lv_example_msgbox_2.c b/examples/widgets/msgbox/lv_example_msgbox_2.c index 793a9c4dff..134f4fcaee 100644 --- a/examples/widgets/msgbox/lv_example_msgbox_2.c +++ b/examples/widgets/msgbox/lv_example_msgbox_2.c @@ -7,6 +7,19 @@ static void minimize_button_event_cb(lv_event_t * e) lv_obj_add_flag(mbox, LV_OBJ_FLAG_HIDDEN); } +/** + * @title Settings dialog with minimize button + * @brief A 300x200 non-modal settings panel with Brightness and Speed sliders. + * + * A non-modal `lv_msgbox` on the active screen gets a header with + * title `Setting`, a close icon, and a minus header button whose + * `LV_EVENT_CLICKED` handler hides the panel with + * `LV_OBJ_FLAG_HIDDEN`. `lv_msgbox_get_content` is flipped to + * `LV_FLEX_FLOW_COLUMN` and holds two column containers that pair a + * label with a full-width `lv_slider`, preset to Brightness 50 and + * Speed 80. The footer adds flex-growing `Apply` and `Cancel` + * buttons tinted indigo. + */ void lv_example_msgbox_2(void) { lv_obj_t * setting = lv_msgbox_create(lv_screen_active()); diff --git a/examples/widgets/msgbox/lv_example_msgbox_3.c b/examples/widgets/msgbox/lv_example_msgbox_3.c index 9e5b7407ca..cbc47018af 100644 --- a/examples/widgets/msgbox/lv_example_msgbox_3.c +++ b/examples/widgets/msgbox/lv_example_msgbox_3.c @@ -20,6 +20,18 @@ static void dropdown_value_changed_event_cb(lv_event_t * e) } } +/** + * @title Blurred message box over background + * @brief Toggle a blur radius between the screen backdrop and the message box itself. + * + * A long Lorem ipsum `lv_label` fills 60% width behind a translucent + * `lv_msgbox` placed on `lv_layer_top()` with a black header and + * body at `LV_OPA_40` and `blur_backdrop` enabled. A `lv_dropdown` + * offering `Blur screen` and `Blur msgbox` is anchored at (5, 5); its + * `LV_EVENT_VALUE_CHANGED` callback sets a blur radius of 24 on + * either `lv_layer_top()` or the message box. A synthetic event is + * sent to initialize the state. + */ void lv_example_msgbox_3(void) { diff --git a/examples/widgets/obj/about.md b/examples/widgets/obj/about.md new file mode 100644 index 0000000000..3858af3721 --- /dev/null +++ b/examples/widgets/obj/about.md @@ -0,0 +1,6 @@ +--- +title: "Base Widget" +order: 5 +--- + +The `lv_obj_t` base class that every other widget inherits from, usable directly as a container or styling surface. diff --git a/examples/widgets/obj/lv_example_obj_1.c b/examples/widgets/obj/lv_example_obj_1.c index 322306e4ab..cad024f92d 100644 --- a/examples/widgets/obj/lv_example_obj_1.c +++ b/examples/widgets/obj/lv_example_obj_1.c @@ -1,6 +1,16 @@ #include "../../lv_examples.h" #if LV_BUILD_EXAMPLES +/** + * @title Base objects with and without shadow + * @brief Two base objects showing default styling next to a custom blue shadow. + * + * Two `lv_obj` base objects are placed on the active screen. The + * first, sized 100 by 50, uses the default theme. The second keeps + * the default size and picks up a shared `lv_style_t` with a blue + * 10 px shadow spread by 5 px. Both are offset from center so the + * shadow difference is visible side by side. + */ void lv_example_obj_1(void) { lv_obj_t * obj1; diff --git a/examples/widgets/obj/lv_example_obj_2.c b/examples/widgets/obj/lv_example_obj_2.c index 909ae6bb24..473aae6c79 100644 --- a/examples/widgets/obj/lv_example_obj_2.c +++ b/examples/widgets/obj/lv_example_obj_2.c @@ -17,7 +17,14 @@ static void drag_event_handler(lv_event_t * e) } /** - * Make an object draggable. + * @title Draggable base object + * @brief Move a `Drag me` object under the pointer using `LV_EVENT_PRESSING`. + * + * A 150 by 100 base object carries a centered `Drag me` label. An + * `LV_EVENT_PRESSING` callback reads the active input device's motion + * vector with `lv_indev_get_vect`, adds it to the object's current + * aligned position, and calls `lv_obj_set_pos` so the object follows + * the pointer as long as it is held down. */ void lv_example_obj_2(void) { diff --git a/examples/widgets/obj/lv_example_obj_3.c b/examples/widgets/obj/lv_example_obj_3.c index bb5979fc7f..e9b0db614c 100644 --- a/examples/widgets/obj/lv_example_obj_3.c +++ b/examples/widgets/obj/lv_example_obj_3.c @@ -21,6 +21,17 @@ static void timer_cb(lv_timer_t * timer) } } +/** + * @title Animated matrix transform on a base object + * @brief Continuously scale and rotate a centered object using `lv_obj_set_transform`. + * + * A centered base object is paired with a 20 ms `lv_timer` that + * builds an identity `lv_matrix_t`, scales its x axis, rotates it by + * 360 times the scale factor, and applies the result with + * `lv_obj_set_transform`. The scale factor grows from 0.1 to 2.0 in + * 0.01 steps; once it exceeds 2.0 the object is reset with + * `lv_obj_reset_transform` and the loop restarts. + */ void lv_example_obj_3(void) { lv_obj_t * obj = lv_obj_create(lv_screen_active()); diff --git a/examples/widgets/roller/about.md b/examples/widgets/roller/about.md new file mode 100644 index 0000000000..1cf2697786 --- /dev/null +++ b/examples/widgets/roller/about.md @@ -0,0 +1,6 @@ +--- +title: "Roller" +order: 115 +--- + +Scrollable cylindrical selector for picking one option from a fixed list, configured via `lv_roller_set_options`. diff --git a/examples/widgets/roller/lv_example_roller_1.c b/examples/widgets/roller/lv_example_roller_1.c index 72dbbb5c47..d360cfc37b 100644 --- a/examples/widgets/roller/lv_example_roller_1.c +++ b/examples/widgets/roller/lv_example_roller_1.c @@ -13,7 +13,14 @@ static void event_handler(lv_event_t * e) } /** - * An infinite roller with the name of the months + * @title Infinite month roller + * @brief Pick a month from a wrap-around roller and log the selection. + * + * A centered `lv_roller` is populated with the twelve English month names in + * `LV_ROLLER_MODE_INFINITE`, so scrolling past December wraps back to January. + * Four rows are visible at once via `lv_roller_set_visible_row_count`. An + * `LV_EVENT_ALL` handler prints the current selection string on + * `LV_EVENT_VALUE_CHANGED`. */ void lv_example_roller_1(void) { diff --git a/examples/widgets/roller/lv_example_roller_2.c b/examples/widgets/roller/lv_example_roller_2.c index 55f261f4ef..14cdb33ec3 100644 --- a/examples/widgets/roller/lv_example_roller_2.c +++ b/examples/widgets/roller/lv_example_roller_2.c @@ -13,7 +13,16 @@ static void event_handler(lv_event_t * e) } /** - * Roller with various alignments and larger text in the selected area + * @title Rollers sharing a selected-row style + * @brief One `LV_PART_SELECTED` style is reused across three number rollers of different widths. + * + * A shared style for `LV_PART_SELECTED` swaps in `lv_font_montserrat_22` with a + * pink fill and red border. Three `LV_ROLLER_MODE_NORMAL` rollers list numbers + * `1..10`: a 100 px left-aligned roller with a green vertical gradient + * background and two visible rows, a default-width center roller with three + * visible rows, and an 80 px right-aligned roller with four visible rows. Each + * roller starts on a different selection (2, 5, 8) with `LV_ANIM_OFF` and logs + * on `LV_EVENT_VALUE_CHANGED`. */ void lv_example_roller_2(void) { diff --git a/examples/widgets/roller/lv_example_roller_3.c b/examples/widgets/roller/lv_example_roller_3.c index e4c50bc27c..ad384102f7 100644 --- a/examples/widgets/roller/lv_example_roller_3.c +++ b/examples/widgets/roller/lv_example_roller_3.c @@ -36,7 +36,16 @@ static void generate_mask(lv_draw_buf_t * mask) } /** - * Add a fade mask to roller. + * @title Roller with top and bottom fade + * @brief Fade the roller edges to black using a generated bitmap mask. + * + * The active screen is tinted `LV_PALETTE_BLUE_GREY` and a month roller in + * `LV_ROLLER_MODE_NORMAL` takes a style that paints it black with white text + * and no border. A 130x150 `LV_COLOR_FORMAT_L8` draw buffer is filled on a + * canvas with two `LV_GRAD_DIR_VER` rectangles (black-to-white on top, + * white-to-black on bottom), leaving the middle opaque. The resulting buffer is + * attached through `lv_obj_set_style_bitmap_mask_src` so the first and last + * rows fade out. */ void lv_example_roller_3(void) { diff --git a/examples/widgets/scale/about.md b/examples/widgets/scale/about.md new file mode 100644 index 0000000000..95e0a8bf69 --- /dev/null +++ b/examples/widgets/scale/about.md @@ -0,0 +1,6 @@ +--- +title: "Scale" +order: 120 +--- + +Linear or circular axis with tick marks and labels, used as a standalone ruler or as a base for gauges. diff --git a/examples/widgets/scale/lv_example_scale_1.c b/examples/widgets/scale/lv_example_scale_1.c index 2a53774843..7a5863e27b 100644 --- a/examples/widgets/scale/lv_example_scale_1.c +++ b/examples/widgets/scale/lv_example_scale_1.c @@ -2,7 +2,13 @@ #if LV_USE_SCALE && LV_BUILD_EXAMPLES /** - * A simple horizontal scale + * @title Horizontal scale with labels + * @brief Place a bottom-labelled horizontal scale across 80% of the screen. + * + * A scale is created with `LV_SCALE_MODE_HORIZONTAL_BOTTOM`, sized to + * 80% width and 100 px height, and centered. It has 31 ticks with every + * fifth promoted to a major tick, minor ticks 5 px long and major ticks + * 10 px long, and a value range from 10 to 40. */ void lv_example_scale_1(void) { diff --git a/examples/widgets/scale/lv_example_scale_10.c b/examples/widgets/scale/lv_example_scale_10.c index b7005132ef..0f745d0727 100644 --- a/examples/widgets/scale/lv_example_scale_10.c +++ b/examples/widgets/scale/lv_example_scale_10.c @@ -83,6 +83,20 @@ static void add_section(lv_obj_t * target_scale, lv_scale_set_section_style_main(target_scale, sec, &styles->main); } +/** + * @title Heart-rate zone gauge with animated needle + * @brief Round inner scale coloured by five heart-rate zones with a bpm readout. + * + * A 200 by 200 scale uses `LV_SCALE_MODE_ROUND_INNER` over the range + * 98 to 195 bpm with a 280 degree sweep rotated to 130 degrees and + * 15 ticks (major every third). Five sections colour the arc grey, + * blue, green, orange, and red for zones 1 through 5, and a black + * `lv_line` needle is placed with `lv_scale_set_line_needle_value`. A + * centred circular overlay holds a flex-column container with a + * Montserrat 40 bpm value and a Montserrat 18 `bpm` label. An 80 ms + * `lv_timer` sweeps the displayed heart rate between 98 and 195, + * updating the needle, the value, and the zone-matching text colour. + */ void lv_example_scale_10(void) { scale = lv_scale_create(lv_screen_active()); diff --git a/examples/widgets/scale/lv_example_scale_11.c b/examples/widgets/scale/lv_example_scale_11.c index a419d4f58d..21b509d2f9 100644 --- a/examples/widgets/scale/lv_example_scale_11.c +++ b/examples/widgets/scale/lv_example_scale_11.c @@ -23,6 +23,21 @@ static void label_color_cb(lv_event_t * e) } } +/** + * @title 24-hour day and night dial + * @brief Round outer scale split into coloured day and night arcs with sunrise and sunset text. + * + * A 210 by 210 dark grey container hosts a 150 by 150 + * `LV_SCALE_MODE_ROUND_OUTER` scale over the range 0 to 24 with a + * full 360 degree sweep rotated to 105 degrees and 25 hourly ticks in + * `lv_font_montserrat_12`. Labels `01` through `24` rotate to follow + * the ticks while staying upright, and an `LV_EVENT_DRAW_TASK_ADDED` + * callback whitens the `06`, `12`, `18`, and `24` labels while + * greying the rest. Two sections colour the arc blue for 17 to 5 + * (night) and dark yellow for 5 to 17 (day). Inside the container, + * a top `TODAY` heading sits above `SUNRISE 6:43` on the left and + * `SUNSET 17:37` on the right, using `lv_font_montserrat_14` through `_20`. + */ void lv_example_scale_11(void) { lv_obj_t * bg = lv_obj_create(lv_screen_active()); diff --git a/examples/widgets/scale/lv_example_scale_12.c b/examples/widgets/scale/lv_example_scale_12.c index e38111921e..5001b1bbaf 100644 --- a/examples/widgets/scale/lv_example_scale_12.c +++ b/examples/widgets/scale/lv_example_scale_12.c @@ -50,7 +50,18 @@ static void draw_event_cb(lv_event_t * e) } /** - * A round scale style simulating a compass + * @title Rotating compass with cardinal labels + * @brief Round scale rotates under a fixed arrow as its heading sweeps 0 to 360. + * + * A 200 by 200 scale uses `LV_SCALE_MODE_ROUND_INNER` over 0 to 360 + * with a 360 degree sweep, 61 ticks, and custom labels alternating + * `N`, `30`, `60`, `E`, and so on. A red `LV_SYMBOL_UP` label pins + * the forward bearing at the top, and a centre label formats the + * heading as `` plus the cardinal string from + * `heading_to_cardinal`. An `LV_EVENT_DRAW_TASK_ADDED` callback paints + * the `N` label and its tick red. An infinite 5000 ms forward and + * reverse animation drives `lv_scale_set_rotation`, turning the dial + * beneath the arrow. */ void lv_example_scale_12(void) { diff --git a/examples/widgets/scale/lv_example_scale_2.c b/examples/widgets/scale/lv_example_scale_2.c index 5b74fbe526..27d92249af 100644 --- a/examples/widgets/scale/lv_example_scale_2.c +++ b/examples/widgets/scale/lv_example_scale_2.c @@ -2,7 +2,16 @@ #if LV_USE_SCALE && LV_BUILD_EXAMPLES /** - * An vertical scale with section and custom styling + * @title Vertical scale with red upper band + * @brief Celsius-labelled right-side vertical scale turning red above 75. + * + * A 60 by 200 scale uses `LV_SCALE_MODE_VERTICAL_RIGHT` with 21 ticks + * (major every fifth) over the range 0 to 100 and a custom label array + * (`0 °C` through `100 °C`). Blue styles are applied to + * `LV_PART_MAIN`, `LV_PART_INDICATOR`, and `LV_PART_ITEMS`, and a red + * section covering 75 to 100 overrides those styles via + * `lv_scale_add_section`. A translucent blue-grey background rounds out + * the widget with padding and corner radius. */ void lv_example_scale_2(void) { diff --git a/examples/widgets/scale/lv_example_scale_3.c b/examples/widgets/scale/lv_example_scale_3.c index 252cb24ec2..9edb006509 100644 --- a/examples/widgets/scale/lv_example_scale_3.c +++ b/examples/widgets/scale/lv_example_scale_3.c @@ -17,7 +17,16 @@ static void set_needle_img_value(void * obj, int32_t v) } /** - * A simple round scale + * @title Round scales with animated needles + * @brief Two round inner scales driven by looping line and image needles. + * + * Two 150 by 150 scales use `LV_SCALE_MODE_ROUND_INNER` with a 270 + * degree range rotated to 135 degrees, 31 ticks, and the range 10 to + * 40. The left scale attaches an `lv_line` needle driven by + * `lv_scale_set_line_needle_value`; the right one attaches an + * `lv_image` needle (`img_hand`) driven by + * `lv_scale_set_image_needle_value`. Both needles animate between 10 + * and 40 on an infinite 1000 ms forward and 1000 ms reverse loop. */ void lv_example_scale_3(void) { diff --git a/examples/widgets/scale/lv_example_scale_4.c b/examples/widgets/scale/lv_example_scale_4.c index 466279fd58..1258b2e50d 100644 --- a/examples/widgets/scale/lv_example_scale_4.c +++ b/examples/widgets/scale/lv_example_scale_4.c @@ -2,7 +2,15 @@ #if LV_USE_SCALE && LV_BUILD_EXAMPLES /** - * A round scale with section and custom styling + * @title Round outer scale with red upper band + * @brief Celsius-labelled round outer scale turning red above 75. + * + * A 150 by 150 scale uses `LV_SCALE_MODE_ROUND_OUTER` with 21 ticks + * (major every fifth), the range 0 to 100, and a custom label array + * (`0 °C` through `100 °C`). Blue styles are applied to + * `LV_PART_MAIN` (as an arc), `LV_PART_INDICATOR`, and `LV_PART_ITEMS`; + * a section from 75 to 100 overrides those with red arc and tick + * styles via `lv_scale_add_section`. */ void lv_example_scale_4(void) { diff --git a/examples/widgets/scale/lv_example_scale_5.c b/examples/widgets/scale/lv_example_scale_5.c index 1a1cb0bd61..f06142c467 100644 --- a/examples/widgets/scale/lv_example_scale_5.c +++ b/examples/widgets/scale/lv_example_scale_5.c @@ -2,7 +2,16 @@ #if LV_USE_SCALE && LV_BUILD_EXAMPLES /** - * An scale with section and custom styling + * @title Custom labels and hex-coloured styles + * @brief Default-mode scale with two named ticks and a magenta/red/blue palette. + * + * A scale sized to half the display resolution carries 10 total ticks + * (major every fifth) across the range 25 to 35, with two custom + * labels `One` and `Two`. Styles set via `lv_color_hex` colour the main + * line blue, the minor ticks red, and the major tick labels magenta + * with green tick lines. A section from 25 to 30 overrides the + * indicator and items styles with spaced red text and blue minor + * ticks. */ void lv_example_scale_5(void) { diff --git a/examples/widgets/scale/lv_example_scale_6.c b/examples/widgets/scale/lv_example_scale_6.c index 0a5503577d..a2f7d2c7b1 100644 --- a/examples/widgets/scale/lv_example_scale_6.c +++ b/examples/widgets/scale/lv_example_scale_6.c @@ -49,7 +49,17 @@ static void timer_cb(lv_timer_t * timer) } /** - * A round scale with multiple needles, resembling a clock + * @title Analog clock face with two hands + * @brief Round inner scale that advances minute and hour hands on a timer. + * + * A 150 by 150 scale uses `LV_SCALE_MODE_ROUND_INNER` with a 360 + * degree range rotated to 270 degrees, 61 ticks (major every fifth), + * and hour labels `12` through `11`. Two `lv_line` hands are added: + * the white minute hand stores its points in a caller-owned buffer via + * `lv_line_set_points_mutable`, while the red hour hand lets the scale + * allocate points internally. A 250 ms `lv_timer` advances the clock + * by one minute per tick, re-positioning both hands with + * `lv_scale_set_line_needle_value`. */ void lv_example_scale_6(void) { diff --git a/examples/widgets/scale/lv_example_scale_7.c b/examples/widgets/scale/lv_example_scale_7.c index 8bf376ecaf..9b2bef4378 100644 --- a/examples/widgets/scale/lv_example_scale_7.c +++ b/examples/widgets/scale/lv_example_scale_7.c @@ -47,7 +47,16 @@ static void draw_event_cb(lv_event_t * e) } /** - * Customizing scale major tick label color with `LV_EVENT_DRAW_TASK_ADDED` event + * @title Rainbow major-tick labels via draw task + * @brief Recolour and reformat scale labels during `LV_EVENT_DRAW_TASK_ADDED`. + * + * A horizontal-bottom scale (80% width, 100 px tall, 31 ticks, range + * 10 to 40) enables `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` and subscribes + * to `LV_EVENT_DRAW_TASK_ADDED`. The callback inspects each draw + * task targeting `LV_PART_INDICATOR`, rewrites the label text to a + * one-decimal value formatted from `id2`, picks one of seven palette + * colours by tick index, and expands the draw area to fit the new + * text width. */ void lv_example_scale_7(void) { diff --git a/examples/widgets/scale/lv_example_scale_8.c b/examples/widgets/scale/lv_example_scale_8.c index 4936919952..0d28facbf4 100644 --- a/examples/widgets/scale/lv_example_scale_8.c +++ b/examples/widgets/scale/lv_example_scale_8.c @@ -3,7 +3,17 @@ /** - * A simple round scale with label/tick translation + * @title Round scale with rotated upright labels + * @brief Round inner scale whose labels follow ticks while staying upright. + * + * A 150 by 150 scale uses `LV_SCALE_MODE_ROUND_INNER` with a 270 + * degree range rotated to 135 degrees, 31 ticks over the range 10 to + * 40. The indicator part applies + * `LV_SCALE_LABEL_ROTATE_MATCH_TICKS | LV_SCALE_LABEL_ROTATE_KEEP_UPRIGHT`, + * a 10 px horizontal translate, a 15 px tick length, and a 10 px + * radial offset. Minor ticks get a 10 px length, a 5 px radial offset, + * and 50% line opacity. A static `lv_line` needle is anchored at + * value 33. */ void lv_example_scale_8(void) { diff --git a/examples/widgets/scale/lv_example_scale_9.c b/examples/widgets/scale/lv_example_scale_9.c index b475697024..fb71590125 100644 --- a/examples/widgets/scale/lv_example_scale_9.c +++ b/examples/widgets/scale/lv_example_scale_9.c @@ -2,7 +2,14 @@ #if LV_USE_SCALE && LV_BUILD_EXAMPLES /** - * A simple horizontal scale with transforms + * @title Tilted major ticks on horizontal scale + * @brief Horizontal scale whose major ticks rotate 45 degrees with a translate offset. + * + * A 200 by 100 horizontal-bottom scale carries 31 ticks (major every + * fifth) over the range 10 to 40. The indicator part receives a + * transform rotation of 450 (45.0 degrees), a 30 px tick length, and a + * 5 px x-translate, leaning each major tick and its label away from + * vertical. Minor ticks keep a 5 px length and straight orientation. */ void lv_example_scale_9(void) { diff --git a/examples/widgets/slider/about.md b/examples/widgets/slider/about.md new file mode 100644 index 0000000000..748a607904 --- /dev/null +++ b/examples/widgets/slider/about.md @@ -0,0 +1,4 @@ +--- +title: "Slider" +order: 125 +--- diff --git a/examples/widgets/slider/lv_example_slider_1.c b/examples/widgets/slider/lv_example_slider_1.c index b78f74b4ce..1a4c0470fa 100644 --- a/examples/widgets/slider/lv_example_slider_1.c +++ b/examples/widgets/slider/lv_example_slider_1.c @@ -5,7 +5,14 @@ static void slider_event_cb(lv_event_t * e); static lv_obj_t * slider_label; /** - * A default slider with a label displaying the current value + * @title Slider with live value label + * @brief Center a slider and update a percentage label beneath it on value changes. + * + * A default `lv_slider_create` slider is centered on the active screen with a + * 2000 ms `LV_STYLE_ANIM_DURATION` for smooth programmatic moves. A label + * starting at `0%` is placed with `LV_ALIGN_OUT_BOTTOM_MID` below the slider, + * and an `LV_EVENT_VALUE_CHANGED` callback rewrites the label with the + * current `lv_slider_get_value` and realigns it under the slider. */ void lv_example_slider_1(void) { diff --git a/examples/widgets/slider/lv_example_slider_2.c b/examples/widgets/slider/lv_example_slider_2.c index 7cfeff745c..196dd38cdc 100644 --- a/examples/widgets/slider/lv_example_slider_2.c +++ b/examples/widgets/slider/lv_example_slider_2.c @@ -2,7 +2,16 @@ #if LV_USE_SLIDER && LV_BUILD_EXAMPLES /** - * Show how to style a slider. + * @title Fully styled slider parts + * @brief Restyle every part of a slider with a cyan palette and pressed-state darkening. + * + * The theme styles are removed from a centered slider and four local styles + * are attached. The `LV_PART_MAIN` track is grey with negative vertical + * padding so the indicator overflows, the `LV_PART_INDICATOR` uses + * `LV_PALETTE_CYAN`, and the `LV_PART_KNOB` adds a darker border plus 6 px + * padding. A shared pressed-state style darkens both the indicator and knob, + * and a 300 ms linear transition on `LV_STYLE_BG_COLOR` cross-fades the + * color change. */ void lv_example_slider_2(void) { diff --git a/examples/widgets/slider/lv_example_slider_3.c b/examples/widgets/slider/lv_example_slider_3.c index 198ce021a4..5f15ac60c5 100644 --- a/examples/widgets/slider/lv_example_slider_3.c +++ b/examples/widgets/slider/lv_example_slider_3.c @@ -7,8 +7,15 @@ static void slider_event_cb(lv_event_t * e); /** - * Show the current value when the slider is pressed by extending the drawer + * @title Range slider with pressed value tooltip + * @brief Draw the current low-high pair above a range slider only while it is pressed. * + * The slider is set to `LV_SLIDER_MODE_RANGE` over 0 to 100 with a start + * value of 20 and an end value of 70. `LV_EVENT_REFR_EXT_DRAW_SIZE` reserves + * 50 px above the widget so the tooltip has room, and `LV_EVENT_DRAW_MAIN_END` + * draws a ` - ` label centered above the indicator when + * `LV_STATE_PRESSED` is active. Releasing the slider removes the tooltip on + * the next redraw. */ void lv_example_slider_3(void) { diff --git a/examples/widgets/slider/lv_example_slider_4.c b/examples/widgets/slider/lv_example_slider_4.c index 92f5c68c0e..84d76778fd 100644 --- a/examples/widgets/slider/lv_example_slider_4.c +++ b/examples/widgets/slider/lv_example_slider_4.c @@ -5,7 +5,14 @@ static void slider_event_cb(lv_event_t * e); static lv_obj_t * slider_label; /** - * Slider with opposite direction + * @title Reversed slider direction + * @brief Center a slider whose range runs from 100 down to 0 with a live label. + * + * `lv_slider_set_range(slider, 100, 0)` reverses the fill direction so the + * indicator grows from the right and the reported value drops as the knob + * moves right. A label below the slider starts at `0%` and is rewritten from + * `lv_slider_get_value` in the `LV_EVENT_VALUE_CHANGED` callback, then + * realigned with `LV_ALIGN_OUT_BOTTOM_MID`. */ void lv_example_slider_4(void) { diff --git a/examples/widgets/span/about.md b/examples/widgets/span/about.md new file mode 100644 index 0000000000..9cd5e574cc --- /dev/null +++ b/examples/widgets/span/about.md @@ -0,0 +1,6 @@ +--- +title: "Span" +order: 130 +--- + +Rich text container where each `lv_span_t` segment can carry its own style, enabling mixed formatting within one paragraph. diff --git a/examples/widgets/span/lv_example_span_1.c b/examples/widgets/span/lv_example_span_1.c index 93f877366b..a1c2c2b804 100644 --- a/examples/widgets/span/lv_example_span_1.c +++ b/examples/widgets/span/lv_example_span_1.c @@ -14,7 +14,15 @@ static void click_event_cb(lv_event_t * e) } /** - * Create spans and get clicked one + * @title Styled spans with click hit-test + * @brief Stack multiple styled spans in one group and log the clicked segment. + * + * A centered `lv_spangroup` of width 300 and `LV_SIZE_CONTENT` height is styled + * with an orange 1 px border and 20 px indent, and uses + * `LV_SPAN_OVERFLOW_CLIP`. Five spans add text with per-segment color, + * `LV_TEXT_DECOR_UNDERLINE`, `LV_TEXT_DECOR_STRIKETHROUGH`, reduced opacity, and + * alternate fonts. A `LV_EVENT_CLICKED` handler resolves the clicked point to a + * span via `lv_spangroup_get_span_by_point` and logs its text. */ void lv_example_span_1(void) { diff --git a/examples/widgets/spinbox/about.md b/examples/widgets/spinbox/about.md new file mode 100644 index 0000000000..59055ab990 --- /dev/null +++ b/examples/widgets/spinbox/about.md @@ -0,0 +1,6 @@ +--- +title: "Spinbox" +order: 135 +--- + +Numeric input field with increment and decrement controls, configured through `lv_spinbox_set_range` and `lv_spinbox_set_digit_format`. diff --git a/examples/widgets/spinbox/lv_example_spinbox_1.c b/examples/widgets/spinbox/lv_example_spinbox_1.c index 47e8ac1620..ac8bfab2ef 100644 --- a/examples/widgets/spinbox/lv_example_spinbox_1.c +++ b/examples/widgets/spinbox/lv_example_spinbox_1.c @@ -19,6 +19,17 @@ static void lv_spinbox_decrement_event_cb(lv_event_t * e) } } +/** + * @title Spinbox with plus and minus buttons + * @brief Step a fixed-point spinbox with two side buttons that repeat on hold. + * + * A centered spinbox is set to five digits with a decimal point at position 2 + * and a range of `-1000..25000`. `lv_spinbox_step_prev` shifts the active + * digit. Two square buttons sized to the spinbox height sit on either side + * using `LV_SYMBOL_PLUS` and `LV_SYMBOL_MINUS` as background images. Their + * `LV_EVENT_ALL` handlers call `lv_spinbox_increment` or `lv_spinbox_decrement` + * on `LV_EVENT_SHORT_CLICKED` and `LV_EVENT_LONG_PRESSED_REPEAT`. + */ void lv_example_spinbox_1(void) { spinbox = lv_spinbox_create(lv_screen_active()); diff --git a/examples/widgets/spinner/about.md b/examples/widgets/spinner/about.md new file mode 100644 index 0000000000..c50dfb7a08 --- /dev/null +++ b/examples/widgets/spinner/about.md @@ -0,0 +1,4 @@ +--- +title: "Spinner" +order: 140 +--- diff --git a/examples/widgets/spinner/lv_example_spinner_1.c b/examples/widgets/spinner/lv_example_spinner_1.c index ce978b940a..516c52505a 100644 --- a/examples/widgets/spinner/lv_example_spinner_1.c +++ b/examples/widgets/spinner/lv_example_spinner_1.c @@ -1,6 +1,14 @@ #include "../../lv_examples.h" #if LV_USE_SPINNER && LV_BUILD_EXAMPLES +/** + * @title Centered busy spinner + * @brief Place a 100 by 100 spinner on the active screen with custom timing. + * + * A spinner is created on the active screen, sized to 100 by 100, + * centered, and tuned with `lv_spinner_set_anim_params` to a + * 10000 ms loop time and a 200 degree arc length. + */ void lv_example_spinner_1(void) { /*Create a spinner*/ diff --git a/examples/widgets/switch/about.md b/examples/widgets/switch/about.md new file mode 100644 index 0000000000..81d96bd2ae --- /dev/null +++ b/examples/widgets/switch/about.md @@ -0,0 +1,4 @@ +--- +title: "Switch" +order: 145 +--- diff --git a/examples/widgets/switch/lv_example_switch_1.c b/examples/widgets/switch/lv_example_switch_1.c index 0d196cecee..c9635b0241 100644 --- a/examples/widgets/switch/lv_example_switch_1.c +++ b/examples/widgets/switch/lv_example_switch_1.c @@ -11,6 +11,17 @@ static void event_handler(lv_event_t * e) } } +/** + * @title Switch states in a column + * @brief Four switches covering the default, checked, disabled, and checked-disabled states. + * + * The active screen is set to `LV_FLEX_FLOW_COLUMN` with centered flex + * alignment and holds four switches: a default one with + * `LV_OBJ_FLAG_EVENT_BUBBLE` set, a `LV_STATE_CHECKED` switch, a + * `LV_STATE_DISABLED` switch, and one with both states combined. Each one + * subscribes to `LV_EVENT_ALL` and logs `On` or `Off` on + * `LV_EVENT_VALUE_CHANGED` based on `lv_obj_has_state(..., LV_STATE_CHECKED)`. + */ void lv_example_switch_1(void) { lv_obj_set_flex_flow(lv_screen_active(), LV_FLEX_FLOW_COLUMN); diff --git a/examples/widgets/switch/lv_example_switch_2.c b/examples/widgets/switch/lv_example_switch_2.c index ad96f15176..1a38f04fc4 100644 --- a/examples/widgets/switch/lv_example_switch_2.c +++ b/examples/widgets/switch/lv_example_switch_2.c @@ -11,6 +11,17 @@ static void event_handler(lv_event_t * e) } } +/** + * @title Vertical switch orientation + * @brief Two 30 x 60 switches, one horizontal and one forced to vertical orientation. + * + * The active screen is laid out as `LV_FLEX_FLOW_ROW` with centered flex + * alignment. Both switches are sized 30 x 60 so one is taller than it is + * wide; the first keeps the default orientation while the second calls + * `lv_switch_set_orientation(..., LV_SWITCH_ORIENTATION_VERTICAL)` and starts + * in `LV_STATE_CHECKED`. A shared callback logs `On` or `Off` on + * `LV_EVENT_VALUE_CHANGED`. + */ void lv_example_switch_2(void) { lv_obj_set_flex_flow(lv_screen_active(), LV_FLEX_FLOW_ROW); diff --git a/examples/widgets/table/about.md b/examples/widgets/table/about.md new file mode 100644 index 0000000000..afbc4457d7 --- /dev/null +++ b/examples/widgets/table/about.md @@ -0,0 +1,4 @@ +--- +title: "Table" +order: 150 +--- diff --git a/examples/widgets/table/lv_example_table_1.c b/examples/widgets/table/lv_example_table_1.c index d42a90da06..a1d2f7f7af 100644 --- a/examples/widgets/table/lv_example_table_1.c +++ b/examples/widgets/table/lv_example_table_1.c @@ -41,6 +41,19 @@ static void draw_event_cb(lv_event_t * e) } } +/** + * @title Styled table with header and zebra rows + * @brief Two-column fruits-and-prices table with custom header, right-aligned first column, and alternating rows. + * + * A `lv_table` is filled with fruit names in column 0 and dollar prices + * in column 1. The table height is capped at 200 px so the body + * scrolls. With `LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` set, an + * `LV_EVENT_DRAW_TASK_ADDED` callback tints the header row blue and + * center-aligns its text, right-aligns the first column's labels, and + * adds a grey wash on every other body row by editing the + * `lv_draw_fill_dsc_t` and `lv_draw_label_dsc_t` of each + * `LV_PART_ITEMS` task. + */ void lv_example_table_1(void) { lv_obj_t * table = lv_table_create(lv_screen_active()); diff --git a/examples/widgets/table/lv_example_table_2.c b/examples/widgets/table/lv_example_table_2.c index f15d4a1a7a..1843bf1471 100644 --- a/examples/widgets/table/lv_example_table_2.c +++ b/examples/widgets/table/lv_example_table_2.c @@ -57,7 +57,17 @@ static void change_event_cb(lv_event_t * e) } /** - * A very light-weighted list created from table + * @title 200-row list with custom switch cell + * @brief Scrollable 200-item table that draws a toggle switch per row and reports build cost. + * + * `lv_mem_monitor` and `lv_tick_get` bracket the creation of a one-column, + * 200-row table to measure memory and time usage. Each row is filled + * with `lv_table_set_cell_value_fmt`. An `LV_EVENT_DRAW_TASK_ADDED` + * handler intercepts each `LV_PART_ITEMS` fill task and paints a pill + * track and knob whose position and color reflect the row's + * `LV_TABLE_CELL_CTRL_CUSTOM_1` flag. An `LV_EVENT_VALUE_CHANGED` + * handler toggles that flag on the selected row. A bottom label reports + * the row count along with elapsed time and bytes used. */ void lv_example_table_2(void) { diff --git a/examples/widgets/tabview/about.md b/examples/widgets/tabview/about.md new file mode 100644 index 0000000000..a951dcad79 --- /dev/null +++ b/examples/widgets/tabview/about.md @@ -0,0 +1,4 @@ +--- +title: "Tabview" +order: 155 +--- diff --git a/examples/widgets/tabview/lv_example_tabview_1.c b/examples/widgets/tabview/lv_example_tabview_1.c index fe84d71eac..353c661f7e 100644 --- a/examples/widgets/tabview/lv_example_tabview_1.c +++ b/examples/widgets/tabview/lv_example_tabview_1.c @@ -1,6 +1,17 @@ #include "../../lv_examples.h" #if LV_USE_TABVIEW && LV_BUILD_EXAMPLES +/** + * @title Horizontal tab view with three tabs + * @brief Three tabs across the top with a scrollable long label in the first. + * + * `lv_tabview_create` fills the active screen and + * `lv_tabview_add_tab` adds `Tab 1`, `Tab 2`, and `Tab 3`. Tab 1 holds + * a tall multi-line label that exceeds the tab height so it becomes + * scrollable, while Tab 2 and Tab 3 carry short labels. A final + * `lv_obj_scroll_to_view_recursive` on the third-tab label scrolls it + * into view with `LV_ANIM_ON`. + */ void lv_example_tabview_1(void) { /*Create a Tab view object*/ diff --git a/examples/widgets/tabview/lv_example_tabview_2.c b/examples/widgets/tabview/lv_example_tabview_2.c index 7f64ac83e1..01b07009db 100644 --- a/examples/widgets/tabview/lv_example_tabview_2.c +++ b/examples/widgets/tabview/lv_example_tabview_2.c @@ -1,7 +1,19 @@ #include "../../lv_examples.h" #if LV_USE_TABVIEW && LV_BUILD_EXAMPLES -/*A vertical tab view with disabled scrolling and some styling*/ +/** + * @title Left-side vertical tab view + * @brief Five tabs arranged along the left edge with custom colors and swipe scrolling disabled. + * + * `lv_tabview_set_tab_bar_position` sets `LV_DIR_LEFT` and + * `lv_tabview_set_tab_bar_size` reserves 80 px for the tab bar. The + * tab bar is painted dark grey over a red-tinted view body, and each + * tab button gets a right border on `LV_STATE_CHECKED` through + * `lv_obj_set_style_border_side`. Five tabs labeled `Tab 1` to + * `Tab 5` each carry a small label, the second tab is tinted amber, + * and `LV_OBJ_FLAG_SCROLLABLE` is removed from the content so swipes + * no longer pan between tabs. + */ void lv_example_tabview_2(void) { /*Create a Tab view object*/ diff --git a/examples/widgets/textarea/about.md b/examples/widgets/textarea/about.md new file mode 100644 index 0000000000..e15f53df19 --- /dev/null +++ b/examples/widgets/textarea/about.md @@ -0,0 +1,4 @@ +--- +title: "Textarea" +order: 160 +--- diff --git a/examples/widgets/textarea/lv_example_textarea_1.c b/examples/widgets/textarea/lv_example_textarea_1.c index 27c25b0404..e4beabf5be 100644 --- a/examples/widgets/textarea/lv_example_textarea_1.c +++ b/examples/widgets/textarea/lv_example_textarea_1.c @@ -20,6 +20,17 @@ static void btnm_event_handler(lv_event_t * e) } +/** + * @title Single-line textarea with button matrix + * @brief Feed a one-line textarea from a numeric button matrix. + * + * A textarea is placed at the top in one-line mode and forced into + * `LV_STATE_FOCUSED` so the cursor stays visible. A four-row button matrix + * holds digits `0..9` plus `LV_SYMBOL_BACKSPACE` and `LV_SYMBOL_NEW_LINE`. Its + * `LV_EVENT_VALUE_CHANGED` handler appends the pressed character, deletes on + * backspace, or sends `LV_EVENT_READY` to the textarea on new line. The matrix + * drops `LV_OBJ_FLAG_CLICK_FOCUSABLE` so focus stays with the textarea. + */ void lv_example_textarea_1(void) { lv_obj_t * ta = lv_textarea_create(lv_screen_active()); diff --git a/examples/widgets/textarea/lv_example_textarea_2.c b/examples/widgets/textarea/lv_example_textarea_2.c index 8908035b21..499b17d041 100644 --- a/examples/widgets/textarea/lv_example_textarea_2.c +++ b/examples/widgets/textarea/lv_example_textarea_2.c @@ -5,6 +5,16 @@ static void ta_event_cb(lv_event_t * e); static lv_obj_t * kb; +/** + * @title Password and text fields with keyboard + * @brief Two one-line textareas share a keyboard, one masked for password entry. + * + * A left textarea has `lv_textarea_set_password_mode` enabled so input is + * masked, a right textarea keeps plain text, and each is labelled `Password:` + * or `Text:` above it. An `lv_keyboard` occupies the bottom half. A shared + * `LV_EVENT_ALL` handler retargets the keyboard on `LV_EVENT_CLICKED` or + * `LV_EVENT_FOCUSED`, and logs the text on `LV_EVENT_READY`. + */ void lv_example_textarea_2(void) { /*Create the password box*/ diff --git a/examples/widgets/textarea/lv_example_textarea_3.c b/examples/widgets/textarea/lv_example_textarea_3.c index 630a08773b..c9a8ad9356 100644 --- a/examples/widgets/textarea/lv_example_textarea_3.c +++ b/examples/widgets/textarea/lv_example_textarea_3.c @@ -6,8 +6,15 @@ static void ta_event_cb(lv_event_t * e); static lv_obj_t * kb; /** - * Automatically format text like a clock. E.g. "12:34" - * Add the ':' automatically. + * @title Auto-format HH:MM clock input + * @brief Insert the `:` automatically after the first two digits. + * + * A one-line textarea restricts input to `0123456789:` via + * `lv_textarea_set_accepted_chars` and caps the length at 5. A + * `LV_EVENT_VALUE_CHANGED` callback checks the first two characters and, once + * both are digits with no colon in position 2, moves the cursor and calls + * `lv_textarea_add_char(':')`. A numeric `lv_keyboard` in + * `LV_KEYBOARD_MODE_NUMBER` feeds the textarea. */ void lv_example_textarea_3(void) { diff --git a/examples/widgets/textarea/lv_example_textarea_4.c b/examples/widgets/textarea/lv_example_textarea_4.c index 27cfbcb4d1..bd721ba720 100644 --- a/examples/widgets/textarea/lv_example_textarea_4.c +++ b/examples/widgets/textarea/lv_example_textarea_4.c @@ -13,6 +13,17 @@ static void create_styled_textarea_cursor(const char * txt, int32_t y_ofs, lv_st lv_textarea_set_cursor_pos(ta, 0); } +/** + * @title Custom textarea cursor styles + * @brief Apply three different cursor styles to three one-line textareas. + * + * Three `lv_style_t` values are built for `LV_PART_CURSOR | LV_STATE_FOCUSED`. + * The simple style draws only a red border, the underline style disables the + * background and uses `LV_BORDER_SIDE_BOTTOM` with a blue 3 px border, and the + * block style fills with an orange-to-yellow vertical gradient, a red border, + * and a 4 px radius. A helper creates each textarea, forces `LV_STATE_FOCUSED`, + * and attaches one style so the cursor shape matches its label. + */ void lv_example_textarea_4(void) { static lv_style_t style_simple, style_block, style_underline; diff --git a/examples/widgets/tileview/about.md b/examples/widgets/tileview/about.md new file mode 100644 index 0000000000..274b65b3cb --- /dev/null +++ b/examples/widgets/tileview/about.md @@ -0,0 +1,6 @@ +--- +title: "Tileview" +order: 165 +--- + +Grid of full-size tiles that the user pages between by swiping, with each tile added via `lv_tileview_add_tile`. diff --git a/examples/widgets/tileview/lv_example_tileview_1.c b/examples/widgets/tileview/lv_example_tileview_1.c index 413acdb8d5..b92866067b 100644 --- a/examples/widgets/tileview/lv_example_tileview_1.c +++ b/examples/widgets/tileview/lv_example_tileview_1.c @@ -2,9 +2,16 @@ #if LV_USE_TILEVIEW && LV_BUILD_EXAMPLES /** - * Create a 2x2 tile view and allow scrolling only in an "L" shape. - * Demonstrate scroll chaining with a long list that - * scrolls the tile view when it can't be scrolled further. + * @title L-shaped tile view with scroll chaining + * @brief Three tiles in an L layout where a ten-item list chains its scroll to the tile view. + * + * `lv_tileview_add_tile` places a label tile at (0, 0) allowing + * `LV_DIR_BOTTOM`, a button tile at (0, 1) allowing `LV_DIR_TOP` and + * `LV_DIR_RIGHT`, and a list tile at (1, 1) allowing `LV_DIR_LEFT`. + * The button tile holds a centered `lv_button` labeled + * `Scroll up or right`; the list tile holds a full-size `lv_list` + * with ten buttons `One` through `Ten` whose scroll chains back into + * the tile view when the list reaches its edge. */ void lv_example_tileview_1(void) { diff --git a/examples/widgets/win/about.md b/examples/widgets/win/about.md new file mode 100644 index 0000000000..49ae9bacc7 --- /dev/null +++ b/examples/widgets/win/about.md @@ -0,0 +1,6 @@ +--- +title: "Window" +order: 170 +--- + +Container with a title bar and content area, created by `lv_win_create` with header buttons added via `lv_win_add_button`. diff --git a/examples/widgets/win/lv_example_win_1.c b/examples/widgets/win/lv_example_win_1.c index 7d3b70440c..c7cc99ac4a 100644 --- a/examples/widgets/win/lv_example_win_1.c +++ b/examples/widgets/win/lv_example_win_1.c @@ -8,6 +8,18 @@ static void event_handler(lv_event_t * e) LV_LOG_USER("Button %d clicked", (int)lv_obj_get_index(obj)); } +/** + * @title Window with title and toolbar buttons + * @brief A window whose header carries three symbol buttons over a scrollable label body. + * + * `lv_win_create` fills the active screen and `lv_win_add_button` + * places a 40 px `LV_SYMBOL_LEFT`, a 40 px `LV_SYMBOL_RIGHT`, and a + * 60 px `LV_SYMBOL_CLOSE` button on the header around a + * `lv_win_add_title` of `A title`. Each button fires an + * `LV_EVENT_CLICKED` handler that logs its child index. The content + * area from `lv_win_get_content` holds a long multi-line `lv_label` + * that makes the window scroll. + */ void lv_example_win_1(void) { lv_obj_t * win = lv_win_create(lv_screen_active());