Clarify docs about creating custom widgets

[TomJGooding]

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.

[rodrigogiraoserrao]

(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

1. compound widgets;
2. the method render; or
3. 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.

[TomJGooding]

(Hey Tom, where's the compound widget that inherits from Static? I can't find it!)

Do you mean in the tutorial?

textual/docs/examples/tutorial/stopwatch02.py

Lines 10 to 18 in 95f0c39

	class Stopwatch(Static):
	"""A stopwatch widget."""
	def compose(self) -> ComposeResult:
	"""Create child widgets of a stopwatch."""
	yield Button("Start", id="start", variant="success")
	yield Button("Stop", id="stop", variant="error")
	yield Button("Reset", id="reset")
	yield TimeDisplay("00:00:00.00")

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.

[rodrigogiraoserrao]

Do you mean in the tutorial?

I thought you were talking about the guide itself. Yeah, there's plenty of Statics in the tutorial.

[TomJGooding]

Ah no, sorry to "confound this confusion" (clearly my brain wasn't fully engaged when I wrote that!)

[rodrigogiraoserrao]

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 😝

[dmakhno]

Went here trying to understand how to create "Containers", and only few days using/enjoing Textual.

What is very confusing for me as a nubiee.

https://textual.textualize.io/tutorial/

class Stopwatch(Static):

via Static - Stopwatch behaves as container.
(Not sure if Stopwatch is The Widget, in terminology. Thus carefully using "container")

When I go to check manual for Static
https://textual.textualize.io/widgets/static/

NOT Focusable
NOT Container

So can I use Static is the most basic container.

[TomJGooding]

I agree that the documentation is currently a bit confusing on this topic.

Perhaps the Textual maintainers could weigh in here, but I really don't think Static should be used as the base for compound widgets. There's nothing that will break if you do, but really Static is designed to render rather than compose.

Of course it depends on your application, but it is probably better to use Widget or simply one of Textual's containers.