4.7 KiB
Widgets
In this chapter we will explore widgets in more detail, and how you can create custom widgets of your own.
What is a widget?
A widget is a component of your UI responsible for managing a rectangular region of the screen. Widgets may respond to events in much the same way as an app. In many respects, widgets are like mini-apps.
!!! information
Every widget runs in its own asyncio task.
Custom widgets
There is a growing collection of builtin widgets in Textual, but you can build entirely custom widgets that work in the same way.
The first step in building a widget is to import and extend a widget class. This can either be [Widget][textual.widget.Widget] which is the base class of all widgets, or one of it's subclasses.
Let's create a simple custom widget to display a greeting.
--8<-- "docs/examples/guide/widgets/hello01.py"
The three highlighted lines define a custom widget class with just a [render()][textual.widget.Widget.render] method. Textual will display whatever is returned from render in the content area of your widget. We have returned a string in the code above, but there are other possible return types which we will cover later.
Note that the text contains tags in square brackets, i.e. [b]. This is console markup which allows you to embed various styles within your content. If you run this you will find that World is in bold.
This (very simple) custom widget may be styled in the same was as builtin widgets, and targeted with CSS. Let's add some CSS to this app.
=== "hello02.py"
```python title="hello02.py" hl_lines="13"
--8<-- "docs/examples/guide/widgets/hello02.py"
```
=== "hello02.css"
```sass title="hello02.css"
--8<-- "docs/examples/guide/widgets/hello02.css"
```
The addition of the CSS has completely transformed our custom widget.
Static widget
While you can extend the Widget class, it is generally preferable to extend a subclass for a better starting point. The [Static][textual.widgets.Static] class is a widget subclass which caches the result of render, and provides an [update()][textual.widgets.Static.update] method to update the content area.
Let's use Static to create a widget which cycles through "hello" in various languages.
=== "hello03.py"
```python title="hello03.py"
--8<-- "docs/examples/guide/widgets/hello03.py"
```
=== "hello03.css"
```sass title="hello03.css" hl_lines="32-35"
--8<-- "docs/examples/guide/widgets/hello03.css"
```
=== "Output"
```{.textual path="docs/examples/guide/widgets/hello03.py"}
```
Note that there is no render() method on this widget. The Static class is handling the render for us. Instead we call update() when we want to update the content within the widget.
The next_word method updates the greeting. We call this method from the mount handler to get the first word, and from an click handler to cycle through the hellos when we click the widget.
Rich renderables
In previous examples we've set strings as content for Widgets. You can also use special objects called renderables which can produce more advanced visuals in a Textual app. You can use any renderable defined in Rich or third party libraries.
Lets make a widget that uses a Rich table for its content. The following app is a solution of the classic fizzbuzz problem often used to screen software engineers in job interviews. The problem is this: Count up from 1 to 100, when the number is divisible by 3, output "fizz"; when the number is divisible by 5, output "buzz"; and when the number is divisible by both 3 and 5 output "fizzbuzz".
This app will "play" fizz buzz by displaying a table of the first 15 numbers and columns for fizz and buzz.
=== "fizzbuzz.py"
```python title="fizzbuzz.py" hl_lines="18"
--8<-- "docs/examples/guide/widgets/fizzbuzz.py"
```
=== "fizzbuzz.css"
```sass title="hello03.css" hl_lines="32-35"
--8<-- "docs/examples/guide/widgets/fizzbuzz.css"
```
=== "Output"
```{.textual path="docs/examples/guide/widgets/fizzbuzz.py"}
```
Content size
If you use a rich renderable as content, Textual can auto-detect the dimensions of the output which will become the content area of the widget.
TODO: Widgets docs
- What is a widget
- Defining a basic widget
- Base classes Widget or Static
- Text widgets
- Rich renderable widgets
- Complete widget
- Render line widget API