Gabor Kiss-VamosiandClaude Opus 4.8
fb759bd01a
Deprecate the lv_file_explorer widget. A file explorer is a path header plus a table of directory entries read with the lv_fs API, so it can be built directly from base widgets. Following the deprecation guidelines: - @deprecated Doxygen tags and LV_DEPRECATED on lv_file_explorer_create - LV_LOG_DEPRECATED runtime warning in lv_file_explorer_create - migration-v10.mdx entry pointing to the replacement - the new lv_example_table_file_browser shows the recommended approach Live call sites in the kept legacy examples and the test are wrapped with LV_DEPRECATIONS_IGNORE_BEGIN/END so the -Wdeprecated -Werror build stays clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
LVGL Examples
The examples shown in the widget documentation live here. The fastest way to add one is to copy an existing example next to the one you're adding and adjust it — the surrounding files already follow every convention.
Two kinds
- XML (preferred) —
lv_example_<module>_<feature>.xmlin its own<module>/<feature>/folder. Use for anything declarative: layout, styling, properties, data binding. The C examples are generated from it, see below. - C-only —
lv_example_<module>_<feature>.cdirectly in the<module>/folder. Use only when the point is imperative C that XML can't express (event callbacks, animations, draw events), or a feature XML doesn't support yet.
Most widgets need many XML examples and zero or one C-only example.
Good examples to copy
- XML:
widgets/arc/lv_example_arc_set_angles.xml - XML with data binding:
widgets/slider/lv_example_slider_bind_value.xml - C-only:
widgets/arc/lv_example_arc_event.c
Generating the C
You write .xml; a script produces the shipped .c. Never hand-edit a
generated .c — your changes will be overwritten.
python scripts/generate_examples.py [path ...] # all examples if no path
Run it after every new or edited XML, then build to confirm it compiles.
The script auto-runs scripts/code-format.py examples at the end so every
generated .c ships astyle-formatted, and then wipes all .c/.h files
from examples/xml_project/ (the CLI's project scaffolding) so they can't
collide with the host project's source globbing.
The generator drives the LVGL Pro editor CLI (lved-cli.js), which
ships with the LVGL Pro editor — see https://lvgl.io/docs/pro. The script
picks it up from your PATH, or point at it explicitly:
python scripts/generate_examples.py --cli /path/to/lved-cli.js [path ...]
Hard rules
- Fit 320×240 — every example runs in that target (see
xml_project/project.xml). Size widgets to fit. - Reuse shared resources — subjects, consts, styles and images come from
xml_project/globals.xml. Don't invent per-example subjects; add toglobals.xmlonly if nothing fits. - One example = one feature. Show a meaningful variation, not defaults.
- Each example is surfaced in the docs with
<LvglExample>.
Comments
Every XML example opens with a comment block directly above <screen>,
plus one in-view hint. Keep the layers distinct — never repeat a sentence:
@title— short, capitalized; mirrors the on-screen label. No "XML".@brief— one sentence, less than 80 chars, ending with a period.- Description — 2–3 sentences after
@brief: name the specific attributes/values that vary and why it's interesting. Self-contained (readable without the doc page). - 💡 hint — first child of
<view>: imperative and specific about what to do and what visibly changes ("Drag each arc; lowerchange_ratelags behind"), not a vague "Adjust the arc".
XML syntax
The XML format and the editor are documented at https://lvgl.io/docs/pro. For the in-tree conventions, the best reference is the existing examples — match the file you copied.