docs: add custom widget subclassing guide

[forntoh]

Summary

• Adds a Custom Widgets documentation page (overview/widgets/custom-widget) describing the supported pattern for customizing how widget values are displayed: subclass an existing widget (or BaseWidgetValue<T>), override the protected virtual draw() method, and compose the custom widget with ITEM_WIDGET instead of the ITEM_RANGE/ITEM_LIST convenience macros.
• Includes a complete example: a custom range widget that displays its value through a stringForValue(const T&) function instead of a printf format string, keeping all inherited editing behavior (UP/DOWN, clamping, cycling, BACK restore).
• Registers the page in the widget overview and ItemWidget toctrees.

Motivation

Documents the pattern that answers #430 (dynamic string for widget values) without any library API change. A maintainer reply with the same pattern has already been posted on the issue: #430 (comment)

Verification

• Sphinx build (make html, clean rebuild): succeeds with the pre-existing warning set only — byte-identical to a clean build before the change; zero warnings from the new page.
• Content verified against source: BaseWidget::draw (protected virtual, src/widget/BaseWidget.h), BaseWidgetValue::draw / WidgetRange::draw / WidgetList::draw behaviors (including that WidgetList::draw formats the selected list entry), ITEM_DRAW_BUFFER_SIZE (64), and ITEM_WIDGET composition/template deduction (src/ItemWidget.h).

References #430

Summary by CodeRabbit

• Documentation
  • Added guidance on creating custom widgets, including display formatting, buffer handling, and an example using value ranges.
  • Added the custom widget guide to the widget documentation listings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ca914a17-6513-45ec-80bd-e8e24ffa88ce

📥 Commits

Reviewing files that changed from the base of the PR and between 86243aa and 95d4861.

📒 Files selected for processing (3)

• docs/source/overview/items/item-widget.rst
• docs/source/overview/widgets/custom-widget.rst
• docs/source/overview/widgets/index.rst

 _______________________________________________
< Finding your faults 10 times faster than Mom. >
 -----------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}