added howto (#3854)

* added howto

* don't need this

* don't need this

* move title

* docstring

Author: willmcgugan

docs/api/renderables.md

@@ -0,0 +1,7 @@
+A collection of Rich renderables which may be returned from a widget's `render()` method.
+
+::: textual.renderables.bar
+::: textual.renderables.blank
+::: textual.renderables.digits
+::: textual.renderables.gradient
+::: textual.renderables.sparkline

docs/examples/how-to/render_compose.py

@@ -0,0 +1,57 @@
+from time import time
+
+from textual.app import App, ComposeResult, RenderableType
+from textual.containers import Container
+from textual.renderables.gradient import LinearGradient
+from textual.widgets import Static
+
+COLORS = [
+    "#881177",
+    "#aa3355",
+    "#cc6666",
+    "#ee9944",
+    "#eedd00",
+    "#99dd55",
+    "#44dd88",
+    "#22ccbb",
+    "#00bbcc",
+    "#0099cc",
+    "#3366bb",
+    "#663399",
+]
+STOPS = [(i / (len(COLORS) - 1), color) for i, color in enumerate(COLORS)]
+
+
+class Splash(Container):
+    """Custom widget that extends Container."""
+
+    DEFAULT_CSS = """
+    Splash {
+        align: center middle;
+    }
+    Static {
+        width: 40;
+        padding: 2 4;
+    }
+    """
+
+    def on_mount(self) -> None:
+        self.auto_refresh = 1 / 30  # (1)!
+
+    def compose(self) -> ComposeResult:
+        yield Static("Making a splash with Textual!")  # (2)!
+
+    def render(self) -> RenderableType:
+        return LinearGradient(time() * 90, STOPS)  # (3)!
+
+
+class SplashApp(App):
+    """Simple app to show our custom widget."""
+
+    def compose(self) -> ComposeResult:
+        yield Splash()
+
+
+if __name__ == "__main__":
+    app = SplashApp()
+    app.run()

docs/how-to/render-and-compose.md

@@ -0,0 +1,62 @@
+# Render and compose
+
+A common question that comes up on the [Textual Discord server](https://discord.gg/Enf6Z3qhVr) is what is the difference between [`render`][textual.widget.Widget.render] and [`compose`][textual.widget.Widget.compose] methods on a widget?
+In this article we will clarify the differences, and use both these methods to build something fun.
+
+<div class="video-wrapper">
+<iframe width="1280" height="922" src="https://www.youtube.com/embed/dYU7jHyabX8" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+</div>
+
+## Which method to use?
+
+Render and compose are easy to confuse because they both ultimately define what a widget will look like, but they have quite different uses. 
+
+The `render` method on a widget returns a [Rich](https://rich.readthedocs.io/en/latest/) renderable, which is anything you could print with Rich.
+The simplest renderable is just text; so `render()` methods often return a string to display inside the widget, but could equally return a [`Text`](https://rich.readthedocs.io/en/latest/text.html) instance, a [`Table`](https://rich.readthedocs.io/en/latest/tables.html), or anything else from Rich (or third party library).
+
+The `compose` method is used to build [*compound* widgets](../guide/widgets.md#compound-widgets) (widgets composed of other widgets).
+
+A general rule of thumb, is that if you implement a `compose` method, there is no need for a `render` method because it is the widgets yielded from `compose` which define how the custom widget will look.
+However, you *can* mix these two methods.
+If you implement both, the `render` method will set the custom widget's *background* and `compose` will add widgets on top of that background.
+
+## Combining render and compose
+
+Let's look at an example that combines both these methods.
+We will create a custom widget with a [linear gradient][textual.renderables.gradient.LinearGradient] as a background.
+The background will be animated (I did promise *fun*)!
+
+=== "render_compose.py"
+
+    ```python
+    --8<-- "docs/examples/how-to/render_compose.py"
+    ```
+
+    1. Refresh the widget 30 times a second.
+    2. Compose our compound widget, which contains a single Static.
+    3. Render a linear gradient in the background.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/how-to/render_compose.py" columns="100" lines="40"}
+    ```
+
+The `Splash` custom widget has a `compose` method which adds a simple `Static` widget to display a message.
+Additionally there is a `render` method which returns a renderable to fill the background with a gradient.
+
+!!! tip
+
+    As fun as this is, spinning animated gradients may be too distracting for most apps!
+
+## Summary
+
+Keep the following in mind when building [custom widgets](../guide/widgets.md).
+
+1. Use `render` to return simple text, or a Rich renderable.
+2. Use `compose` to create a widget out of other widgets.
+3. If you define both, then `render` will be used as a *background*.
+
+
+---
+
+We are here to [help](../help.md)!

mkdocs-nav.yml

@@ -195,6 +195,7 @@ nav:
       - "api/pilot.md"
       - "api/query.md"
       - "api/reactive.md"
+      - "api/renderables.md"
       - "api/screen.md"
       - "api/scrollbar.md"
       - "api/scroll_view.md"
@@ -213,6 +214,7 @@ nav:
       - "how-to/index.md"
       - "how-to/center-things.md"
       - "how-to/design-a-layout.md"
+      - "how-to/render-and-compose.md"
   - "FAQ.md"
   - "roadmap.md"
   - "Blog":

src/textual/renderables/__init__.py

@@ -0,0 +1 @@
+__all__ = ["bar", "blank", "digits", "gradient", "sparkline"]

src/textual/renderables/gradient.py

@@ -2,6 +2,7 @@
 
 from functools import lru_cache
 from math import cos, pi, sin
+from typing import Sequence
 
 from rich.color import Color as RichColor
 from rich.console import Console, ConsoleOptions, RenderResult
@@ -42,17 +43,22 @@ def __rich_console__(
 
 
 class LinearGradient:
-    """Render a linear gradient with a rotation."""
+    """Render a linear gradient with a rotation.
 
-    def __init__(self, angle: float, stops: list[tuple[float, Color]]) -> None:
-        """
+    Args:
+        angle: Angle of rotation in degrees.
+        stops: List of stop consisting of pairs of offset (between 0 and 1) and color.
 
-        Args:
-            angle: Angle of rotation in degrees.
-            stops: List of stop consisting of pairs of offset (between 0 and 1) and colors.
-        """
+    """
+
+    def __init__(
+        self, angle: float, stops: Sequence[tuple[float, Color | str]]
+    ) -> None:
         self.angle = angle
-        self._stops = stops[:]
+        self._stops = [
+            (stop, Color.parse(color) if isinstance(color, str) else color)
+            for stop, color in stops
+        ]
 
     def __rich_console__(
         self, console: Console, options: ConsoleOptions
@@ -75,7 +81,7 @@ def __rich_console__(
         get_color = color_gradient.get_color
         from_color = Style.from_color
 
-        @lru_cache(maxsize=None)
+        @lru_cache(maxsize=1024)
         def get_rich_color(color_offset: int) -> RichColor:
             """Get a Rich color in the gradient.
 

src/textual/scrollbar.py

@@ -221,16 +221,6 @@ class MyScrollBarRender(ScrollBarRender): ...
     ```
     """
 
-    DEFAULT_CSS = """
-    ScrollBar {
-        link-color-hover: ;
-        link-background-hover:;
-        link-style-hover: ;
-        link-color: transparent;
-        link-background: transparent;
-    }
-    """
-
     def __init__(
         self, vertical: bool = True, name: str | None = None, *, thickness: int = 1
     ) -> None:

src/textual/widget.py

@@ -3161,7 +3161,17 @@ def remove_children(self) -> AwaitRemove:
         return await_remove
 
     def render(self) -> RenderableType:
-        """Get renderable for widget.
+        """Get text or Rich renderable for this widget.
+
+        Implement this for custom widgets.
+
+        Example:
+            ```python
+            from textual.app import RenderableType
+
+            def render(self) -> RenderableType:
+                return "Welcome to [bold red]Textual[/]!"
+            ```
 
         Returns:
             Any renderable.