Textualize
Clarify docs about creating custom widgets
The guide to widgets in the docs starts with how to create custom widgets, but compound widgets aren't explained until much later.
I think custom widgets are far more likely to be compound widgets rather than basic renderables. so the order these concepts are introduced is confusing. I wonder if this is partly explains the questions about the difference between render and compose, and also why we see so many compound widgets inherited from Static!
The tutorial also uses Static for a compound widget, which confounds this confusion.
(Hey Tom, where's the compound widget that inherits from Static? I can't find it!)
I do wonder if we should extract parts of this guide into a new guide that should be named something like “Custom widgets” or “Creating a widget”. This page could/should open with a description of the two/three main ways of creating custom widgets, and providing some rules of thumb for the reader to determine whether they'll need to use
- compound widgets;
- the method
render; or - the line API.
Then the guide could explain these three methods.
The other sections like the tooltips, border title and subtitle, content size, text links, etc, could be left in this guide.
(Hey Tom, where's the compound widget that inherits from
Static? I can't find it!)
Do you mean in the tutorial?
https://github.com/Textualize/textual/blob/95f0c39106e0a53d028e36730a06747eeefff8c0/docs/examples/tutorial/stopwatch02.py#L10-L18
I think what might be confusing some people is that Static has a section in the Custom WIdgets guide, but that's about creating a basic renderable rather than a compound widget. Hope that makes sense.
Do you mean in the tutorial?
I thought you were talking about the guide itself. Yeah, there's plenty of Statics in the tutorial.
Ah no, sorry to "confound this confusion" (clearly my brain wasn't fully engaged when I wrote that!)
I misinterpreted that part, sorry.
Well, the guide could probably be broken up and cleaned up because it has been edited and grown over the past releases and it hasn't grown to be the most usable guide ever. This task is in our backlog so we'll eventually get there 😝