Rename constant namespaces from k-prefix to plural form

Current state

All LVGL constant namespaces use a k prefix:

obj.align(lv::kAlign::center);
obj.add_style(style, lv::kPart::main | lv::kState::pressed);
btn.on(lv::kEvent::clicked, handler);
label.long_mode(lv::kLabelLongMode::wrap);

The k prefix was introduced to avoid name collisions with classes in the same lv namespace:

Constant namespace	Collides with
`lv::kState`	`lv::State<T>` (reactive state holder)
`lv::kEvent`	`lv::Event` (event wrapper class)

The prefix was then applied uniformly to all constant namespaces for consistency, even those without an actual collision (e.g. kAlign, kDir, kPart).

What works

Consistent rule: k = constant, no k = class.
No ambiguity once you learn the convention.

What's awkward

The k prefix on namespaces is unconventional. The Google C++ style guide uses k on individual constant names (kMaxRetries), not on namespaces.
New contributors have to learn a project-specific rule before they can guess the right name.
Some names get long: lv::kLabelLongMode::wrap, lv::kScrollbarMode::auto_, lv::kChartUpdateMode::circular.
There is already an older lv::opa (lowercase, in color.hpp) that duplicates lv::kOpa, showing the convention wasn't applied retroactively everywhere.

Proposal: plural namespaces

Rename constant namespaces to their plural form:

obj.align(lv::aligns::center);
obj.add_style(style, lv::parts::main | lv::states::pressed);
btn.on(lv::events::clicked, handler);
label.long_mode(lv::label_long_modes::wrap);

Mapping

Current (`k`-prefix)	Proposed (plural)
`lv::kAlign`	`lv::aligns`
`lv::kPart`	`lv::parts`
`lv::kState`	`lv::states`
`lv::kOpa`	`lv::opacities`
`lv::kDir`	`lv::dirs`
`lv::kFlexFlow`	`lv::flex_flows`
`lv::kFlexAlign`	`lv::flex_aligns`
`lv::kGridAlign`	`lv::grid_aligns`
`lv::kTextAlign`	`lv::text_aligns`
`lv::kTextDecor`	`lv::text_decors`
`lv::kEvent`	`lv::events`
`lv::kArcMode`	`lv::arc_modes`
`lv::kBarMode`	`lv::bar_modes`
`lv::kSliderMode`	`lv::slider_modes`
`lv::kChartType`	`lv::chart_types`
`lv::kChartAxis`	`lv::chart_axes`
`lv::kChartUpdateMode`	`lv::chart_update_modes`
`lv::kLabelLongMode`	`lv::label_long_modes`
`lv::kGradDir`	`lv::grad_dirs`
`lv::kBorderSide`	`lv::border_sides`
`lv::kScrollbarMode`	`lv::scrollbar_modes`
`lv::kScrollSnap`	`lv::scroll_snaps`
`lv::kBlendMode`	`lv::blend_modes`
`lv::kKeyboardMode`	`lv::keyboard_modes`
`lv::kLayout`	`lv::layouts`
`lv::kAnim`	`lv::anims`
`lv::kSize`	`lv::sizes`
`lv::kRadius`	`lv::radii`
`lv::kColorFormat`	`lv::color_formats`

Why plural namespaces over enum classes

Since this is a thin wrapper around LVGL's C API, the underlying types are plain integers (lv_state_t, lv_part_t, etc.) and are frequently combined with bitwise OR. Enum classes would require:

static_cast or conversion operators at every LVGL call boundary
operator| overloads for each enum type
Significant boilerplate for no runtime benefit

Plural namespaces keep the values as constexpr integers that pass straight through to LVGL with zero friction.

Why plural namespaces over k-prefix

Familiar pattern -- plural namespaces are a common C++ idiom (e.g. std::chrono::hours, std::filesystem::perms). No project-specific rule to learn.
Collision-free -- lv::states vs lv::State<T>, lv::events vs lv::Event. Plural nouns naturally don't collide with singular class names.
Reads like English -- lv::parts::main, lv::states::pressed, lv::events::clicked.
Consistent with snake_case -- the rest of the API uses snake_case for functions and namespaces; plural namespaces fit that convention.

Migration path

Add plural namespace aliases (namespace states = kState; etc.)
Update docs and examples to use the new names.
Deprecate k-prefixed names (keep as aliases for one release cycle).
Remove k-prefixed aliases.
Merge lv::opa into lv::opacities and deprecate lv::opa.

Open questions

Are there any plural forms that feel unnatural or ambiguous?
Should widget-specific constants stay nested (e.g. lv::arc::modes instead of lv::arc_modes) to group them by widget?

As someone who if just getting started with LVGL, my opinion is from the "what would an absolutely clueless retired developer think" perspective. Please value it as such.

Should widget-specific constants stay nested (e.g. lv::arc::modes instead of lv::arc_modes) to group them by widget?
I believe the nested version reads much better and is easier to grock, especially if there are other attributes that would be set. Excuse my total lack of knowledge about what else might be set on an arc, but a block of code that defines an arc's modes, it's foos it's bars, it's baz::qux's, it's waldo::fred's, etc. looks and reads better than with the underlines. I can hope that my IDE will help me work my way down the hierarchy a layer at at time.

Are there any plural forms that feel unnatural or ambiguous?
The only one that would not appear to be an easy transition for very experienced LVGL developers (NOT ME, just speculation on my part) is the Radius -> radii as it does not follow the "remove the k, lower case the next letter, go to the end and add an 's'" incantation. But if you mentally remember the first two steps and then let your IDE help you with what needs to be at the end, it should all work out without giving anyone too much of a headache.

Again, please take this for exactly what it is worth, considerably less than the standard two cents.

Thanks,
Arvid

boulabiar/LV_Naming_Proposal.md

Select an option

No results found