Textual

https://textual.textualize.io/
Admin
Textual is a rapid application development framework for Python that enables building sophisticated...
Tokens:568,537
Snippets:5,942
Trust Score:8.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run an example app from the repository

Source: https://textual.textualize.io/getting_started

Navigates to the examples directory and runs the code_browser.py example.

```bash
cd textual/examples/
python code_browser.py ../
```

--------------------------------

### Run setup code with run_before parameter

Source: https://textual.textualize.io/guide/testing

Use the `run_before` parameter to run arbitrary code before the snapshot is captured. In this example, it hovers the mouse cursor over the widget with ID `number-5`.

```python
def test_calculator_hover_number(snap_compare):
    async def run_before(pilot) -> None:
        await pilot.hover("#number-5")

    assert snap_compare("path/to/calculator.py", run_before=run_before)

```

--------------------------------

### Define app, screen, and placeholder header/footer widgets

Source: https://textual.textualize.io/how-to/design-a-layout

This example defines an app, a screen, and header/footer widgets using Placeholder. It is the starting point for designing a layout, working from the outside in. The code is from layout01.py.

```python
from textual.app import App, ComposeResult
from textual.screen import Screen
from textual.widgets import Placeholder


class Header(Placeholder):  
    pass


class Footer(Placeholder):  
    pass


class TweetScreen(Screen):
    def compose(self) -> ComposeResult:
        yield Header(id="Header")  
        yield Footer(id="Footer")  


class LayoutApp(App):
    def on_mount(self) -> None:
        self.push_screen(TweetScreen())


if __name__ == "__main__":
    app = LayoutApp()
    app.run()

```

--------------------------------

### Example of defining MODES and SCREENS

Source: https://textual.textualize.io/api/app

Example showing how to define MODES and SCREENS on an App subclass.

```python
class HelpScreen(Screen[None]):
    ...

class MainAppScreen(Screen[None]):
    ...

class MyApp(App[None]):
    MODES = {
        "default": "main",
        "help": HelpScreen,
    }

    SCREENS = {
        "main": MainAppScreen,
    }

    ...

```

--------------------------------

### Opening tag example

Source: https://textual.textualize.io/guide/content

Shows the syntax of an opening tag that starts a style change.

```markup
[bold]

```

--------------------------------

### Run the stopwatch example

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

Navigate to the tutorial examples directory and run the stopwatch.py script. This launches the stopwatch application.

```bash
cd textual/docs/examples/tutorial
python stopwatch.py

```

--------------------------------

### get_screen(screen, screen_class=None) method signature and example

Source: https://textual.textualize.io/api/app

Method signature for get_screen, which retrieves an installed screen by object or name. The example shows calling it with a screen name and expected class.

```python
get_screen(screen, screen_class=None)

```

```python
my_screen = self.get_screen("settings", MyScreen)

```

--------------------------------

### Run an example with the textual CLI

Source: https://textual.textualize.io/examples/styles

Use the textual run command to execute an example script, such as text_style.py.

```bash
textual run text_style.py

```

--------------------------------

### compose() example implementation

Source: https://textual.textualize.io/api/widget

Example implementation of compose yielding Header, Label, Button, and Footer widgets.

```python
def compose(self) -> ComposeResult:
    yield Header()
    yield Label("Press the button below:")
    yield Button()
    yield Footer()

```

--------------------------------

### Check Hatch installation

Source: https://textual.textualize.io/how-to/package-with-hatch

Run 'hatch' to verify that Hatch is installed correctly and the command is available.

```bash
hatch
```

--------------------------------

### Run a Textual app from a command line script

Source: https://textual.textualize.io/guide/devtools

Runs a Textual app that is installed as a command line script using the `-c` switch. Example runs the `textual colors` command.

```bash
textual run -c textual colors

```

--------------------------------

### CSS syntax examples

Source: https://textual.textualize.io/styles/align

CSS examples showing how to set alignment with `align`, `align-horizontal`, and `align-vertical`. Includes comments for each rule.

```css
/* Align child widgets to the center. */
align: center middle;
/* Align child widget to the top right */
align: right top;

/* Change the horizontal alignment of the children of a widget */
align-horizontal: right;
/* Change the vertical alignment of the children of a widget */
align-vertical: middle;

```

--------------------------------

### assemble example

Source: https://textual.textualize.io/api/content

Example usage of Content.assemble with content, strings, and tuples.

```python
content = Content.assemble(
    Content.from_markup("[b]assemble[/b]: "),  # Other content
    "pieces of text or content into a",  # Simple string of text
    ("a single Content instance", "underline"),  # A tuple of text and a style
)

```

--------------------------------

### ListItem Example

Source: https://textual.textualize.io/widgets/list_item

An example showing how to create a ListView with multiple ListItem widgets in a Textual app.

```APIDOC
## ListItem Example

### Description
This example demonstrates how to use ListItem widgets within a ListView in a Textual application.

### Code
```python
from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, ListItem, ListView


class ListViewExample(App):
    CSS_PATH = "list_view.tcss"

    def compose(self) -> ComposeResult:
        yield ListView(
            ListItem(Label("One")),
            ListItem(Label("Two")),
            ListItem(Label("Three")),
        )
        yield Footer()


if __name__ == "__main__":
    app = ListViewExample()
    app.run()
```
```

--------------------------------

### Python syntax examples

Source: https://textual.textualize.io/styles/align

Python examples showing how to set alignment using `widget.styles.align`, `align_horizontal`, and `align_vertical`. Includes comments for each assignment.

```python
# Align child widgets to the center
widget.styles.align = ("center", "middle")
# Align child widgets to the top right
widget.styles.align = ("right", "top")

# Change the horizontal alignment of the children of a widget
widget.styles.align_horizontal = "right"
# Change the vertical alignment of the children of a widget
widget.styles.align_vertical = "middle"

```

--------------------------------

### Python border examples

Source: https://textual.textualize.io/css_types/border

Python examples showing how to set border styles programmatically using the `styles.border` and `styles.border_bottom` properties.

```python
widget.styles.border = ("heavy", "red")
widget.styles.border_bottom = ("solid", "blue")

```

--------------------------------

### Logging example with self.log

Source: https://textual.textualize.io/api/app

Example usage of the `log` property to log a string and an object.

```python
self.log("Hello, World!")
self.log(self.tree)
```

--------------------------------

### Install the calculator with pip

Source: https://textual.textualize.io/how-to/package-with-hatch

Command for users to install the packaged calculator app via pip.

```bash
pip install textual_calculator

```

--------------------------------

### Install the packaged app with pip

Source: https://textual.textualize.io/how-to/package-with-hatch

Users install the packaged Textual calculator app from PyPI using pip.

```bash
pip install textual-calculator
```

--------------------------------

### Static widget example: simple text label

Source: https://textual.textualize.io/widgets/static

Example from the 'Example' section showing how to use a Static widget as a simple text label. The code creates a Textual app that yields a Static widget with the text 'Hello, world!'.

```python
from textual.app import App, ComposeResult
from textual.widgets import Static


class StaticApp(App):
    def compose(self) -> ComposeResult:
        yield Static("Hello, world!")


if __name__ == "__main__":
    app = StaticApp()
    app.run()

```

--------------------------------

### CSS selector example: .started #start

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

A single CSS rule showing the descendant selector .started #start, which matches the start button only when it is inside a container with the started class. This rule hides the start button when the stopwatch is started.

```css
.started #start {
    display: none
}
```

--------------------------------

### List serve options

Source: https://textual.textualize.io/guide/devtools

Run `textual serve --help` to see additional switches for serving Textual apps.

```bash
textual serve --help
```

--------------------------------

### Install pytest-textual-snapshot

Source: https://textual.textualize.io/guide/testing

Install the official Textual pytest plugin using your favorite package manager. This example uses pip.

```bash
pip install pytest-textual-snapshot
```

--------------------------------

### DocumentBase.get_text_range

Source: https://textual.textualize.io/widgets/text_area

Abstract method that gets the text that falls between the start and end locations.

```APIDOC
## DocumentBase.get_text_range

### Description
Get the text that falls between the start and end locations.

### Method
`get_text_range(start, end)`

### Parameters
- **start** (Location) - Required - The start location of the selection.
- **end** (Location) - Required - The end location of the selection.

### Returns
- **str** - The text between start (inclusive) and end (exclusive).
```

--------------------------------

### MarkdownViewer usage example

Source: https://textual.textualize.io/widgets/markdown_viewer

Example app that displays a MarkdownViewer with a table of contents and disables code indent guides. The markdown content is a string containing the 'Litany Against Fear' text.

```python
class MarkdownExampleApp(App):
    def compose(self) -> ComposeResult:
        markdown_viewer = MarkdownViewer(EXAMPLE_MARKDOWN, show_table_of_contents=True)
        markdown_viewer.code_indent_guides = False
        yield markdown_viewer


if __name__ == "__main__":
    app = MarkdownExampleApp()
    app.run()
```

--------------------------------

### Launch the app from the command line

Source: https://textual.textualize.io/how-to/package-with-hatch

After installation, the app is launched by running the 'calculator' command.

```bash
calculator
```

--------------------------------

### Serve an app from a module

Source: https://textual.textualize.io/guide/devtools

To serve an app from a module, specify the full command including `python`. This example runs the Textual demo.

```bash
textual serve "python -m textual"
```

--------------------------------

### Input validation example

Source: https://textual.textualize.io/widgets/input

Creates an Input widget that only gets validated when the value is submitted explicitly.

```python
input = Input(validate_on=["submitted"])
```

--------------------------------

### get_screen(screen, screen_class=None)

Source: https://textual.textualize.io/api/app

Gets an installed screen by object or name. Optionally expects a specific screen class.

```APIDOC
## get_screen(screen, screen_class=None)

### Description
Get an installed screen. Example: `my_screen = self.get_screen("settings", MyScreen)`

### Method
N/A (Python method)

### Endpoint
N/A

### Parameters
- **screen** (Screen | str) - Required - Either a Screen object or screen name (the `name` argument when installed).
- **screen_class** (Type[Screen] | None) - Optional - Class of expected screen, or `None` for any screen class. Default: `None`

### Raises
- **KeyError** - If the named screen doesn't exist.

### Returns
- **Screen** - A screen instance.

```

--------------------------------

### Python tint examples

Source: https://textual.textualize.io/styles/tint

Two Python examples showing how to set the tint style programmatically: one using `Color.parse().with_alpha()` and one using a string with rgba.

```python
# A red tint
from textual.color import Color
widget.styles.tint = Color.parse("red").with_alpha(0.2);

# A green tint
widget.styles.tint = "rgba(0, 200, 0, 0.3)"
```

--------------------------------

### render() method signature and example

Source: https://textual.textualize.io/api/widget

Get content for the widget. Implement in a subclass for custom widgets. Should return markup, a Content object, or a Rich renderable.

```python
render()
```

```python
from textual.app import RenderResult
from textual.widget import Widget

class CustomWidget(Widget):
    def render(self) -> RenderResult:
        return "Welcome to [bold red]Textual[/]!"
```

--------------------------------

### Basic DirectoryTree example

Source: https://textual.textualize.io/widgets/directory_tree

Creates a simple DirectoryTree that navigates the current working directory.

```python
from textual.app import App, ComposeResult
from textual.widgets import DirectoryTree


class DirectoryTreeApp(App):
    def compose(self) -> ComposeResult:
        yield DirectoryTree("./")


if __name__ == "__main__":
    app = DirectoryTreeApp()
    app.run()

```

--------------------------------

### Simple usage example (loading_indicator.py)

Source: https://textual.textualize.io/widgets/loading_indicator

Creates a minimal Textual app that displays a LoadingIndicator widget. The app's compose method yields the LoadingIndicator, and the app is run when the script is executed.

```python
from textual.app import App, ComposeResult
from textual.widgets import LoadingIndicator


class LoadingApp(App):
    def compose(self) -> ComposeResult:
        yield LoadingIndicator()


if __name__ == "__main__":
    app = LoadingApp()
    app.run()

```

--------------------------------

### Initialize example: reactive property with method default

Source: https://textual.textualize.io/api/reactive

Shows how to use the Initialize class to define a reactive property that calls a method on the parent object to get its default value when first referenced. The example defines an App class with a get_names method and a names reactive property.

```python
class InitializeApp(App):

    def get_names(self) -> list[str]:
        return ["foo", "bar", "baz"]

    # The `names` property will call `get_names` to get its default when first referenced.
    names = reactive(Initialize(get_names))

```

--------------------------------

### pyproject.toml [project] section

Source: https://textual.textualize.io/how-to/package-with-hatch

Example [project] section in pyproject.toml. The dependencies list is initially empty and should be filled with the app's dependencies.

```toml
[project]
name = "textual-calculator"
dynamic = ["version"]
description = 'A example app'
readme = "README.md"
requires-python = ">=3.8"
license = "MIT"
keywords = []
authors = [
  { name = "Will McGugan", email = "redacted@textualize.io" },
]
classifiers = [
  "Development Status :: 4 - Beta",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3.8",
  "Programming Language :: Python :: 3.9",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: Implementation :: CPython",
  "Programming Language :: Python :: Implementation :: PyPy",
]
dependencies = []

```

--------------------------------

### AwaitMount example: await self.mount(Static("foo"))

Source: https://textual.textualize.io/api/widget

Shows how to use the AwaitMount awaitable returned by mount and mount_all. The example awaits the mount of a Static widget.

```python
await self.mount(Static("foo"))
```

--------------------------------

### ProgressBar usage example

Source: https://textual.textualize.io/widgets/progress_bar

A minimal example showing how to create a ProgressBar with a total of 100 steps and advance it by 5 steps when the space key is pressed.

```python
class MyApp(App):
    def compose(self):
        yield ProgressBar(total=100)

    def key_space(self):
        self.query_one(ProgressBar).advance(5)

```

--------------------------------

### Row-span grid example with Python app and TCSS

Source: https://textual.textualize.io/styles/grid/row_span

Complete example of a 4 by 4 grid where placeholders span multiple rows. The Python app defines the grid and placeholders, while the TCSS file sets row-span values for each placeholder and grid layout. Note that grid cells fill left-to-right, top-to-bottom, so #p5 starts in the second row, fourth column.

```python
from textual.app import App
from textual.containers import Grid
from textual.widgets import Placeholder


class MyApp(App):
    CSS_PATH = "row_span.tcss"

    def compose(self):
        yield Grid(
            Placeholder(id="p1"),
            Placeholder(id="p2"),
            Placeholder(id="p3"),
            Placeholder(id="p4"),
            Placeholder(id="p5"),
            Placeholder(id="p6"),
            Placeholder(id="p7"),
        )


if __name__ == "__main__":
    app = MyApp()
    app.run()

```

```css
#p1 {
    row-span: 4;
}
#p2 {
    row-span: 3;
}
#p3 {
    row-span: 2;
}
#p4 {
    row-span: 1;  /* Didn't need to be set explicitly. */
}
#p5 {
    row-span: 3;
}
#p6 {
    row-span: 2;
}
#p7 {
    /* Default value is 1. */
}

Grid {
    grid-size: 4 4;
    grid-gutter: 1 2;
}

Placeholder {
    height: 100%;
}

```

--------------------------------

### Complete TabbedContent example app (tabbed_content.py)

Source: https://textual.textualize.io/widgets/tabbed_content

A full Textual application demonstrating TabbedContent with three tabs, key bindings to switch tabs, and nested TabbedContent. The app starts with the 'jessica' tab active and includes a Footer for key hints.

```python
from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, Markdown, TabbedContent, TabPane

LETO = """
# Duke Leto I Atreides

Head of House Atreides.
"""

JESSICA = """
# Lady Jessica

Bene Gesserit and concubine of Leto, and mother of Paul and Alia.
"""

PAUL = """
# Paul Atreides

Son of Leto and Jessica.
"""


class TabbedApp(App):
    """An example of tabbed content."""

    BINDINGS = [
        ("l", "show_tab('leto')", "Leto"),
        ("j", "show_tab('jessica')", "Jessica"),
        ("p", "show_tab('paul')", "Paul"),
    ]

    def compose(self) -> ComposeResult:
        """Compose app with tabbed content."""
        # Footer to show keys
        yield Footer()

        # Add the TabbedContent widget
        with TabbedContent(initial="jessica"):
            with TabPane("Leto", id="leto"):  # First tab
                yield Markdown(LETO)  # Tab content
            with TabPane("Jessica", id="jessica"):
                yield Markdown(JESSICA)
                with TabbedContent("Paul", "Alia"):
                    yield TabPane("Paul", Label("First child"))
                    yield TabPane("Alia", Label("Second child"))

            with TabPane("Paul", id="paul"):
                yield Markdown(PAUL)

    def action_show_tab(self, tab: str) -> None:
        """Switch to a new tab."""
        self.get_child_by_type(TabbedContent).active = tab


if __name__ == "__main__":
    app = TabbedApp()
    app.run()

```

--------------------------------

### Customize column and tweet sizes with CSS (layout06.py)

Source: https://textual.textualize.io/how-to/design-a-layout

Sets fixed width of 32 for columns and height of 5 for tweets using DEFAULT_CSS. This is the final example, providing a starting point for a real app where placeholders are replaced with builtin or custom widgets.

```python
from textual.app import App, ComposeResult
from textual.containers import HorizontalScroll, VerticalScroll
from textual.screen import Screen
from textual.widgets import Placeholder


class Header(Placeholder):
    DEFAULT_CSS = """
    Header {
        height: 3;
        dock: top;
    }
    """


class Footer(Placeholder):
    DEFAULT_CSS = """
    Footer {
        height: 3;
        dock: bottom;
    }
    """


class Tweet(Placeholder):
    DEFAULT_CSS = """
    Tweet {
        height: 5;
        width: 1fr;
        border: tall $background;
    }
    """


class Column(VerticalScroll):
    DEFAULT_CSS = """
    Column {
        height: 1fr;
        width: 32;
        margin: 0 2;
    }
    """

    def compose(self) -> ComposeResult:
        for tweet_no in range(1, 20):
            yield Tweet(id=f"Tweet{tweet_no}")


class TweetScreen(Screen):
    def compose(self) -> ComposeResult:
        yield Header(id="Header")
        yield Footer(id="Footer")
        with HorizontalScroll():
            yield Column()
            yield Column()
            yield Column()
            yield Column()


class LayoutApp(App):
    def on_ready(self) -> None:
        self.push_screen(TweetScreen())


if __name__ == "__main__":
    app = LayoutApp()
    app.run()
```

--------------------------------

### Async handler example: dictionary app (dictionary.py)

Source: https://textual.textualize.io/guide/events

A complete Textual app that searches a dictionary API as you type. It uses an async handler and asyncio.create_task to run network requests in the background, keeping the UI responsive. Requires httpx (pip install httpx).

```python
import asyncio

try:
    import httpx
except ImportError:
    raise ImportError("Please install httpx with 'pip install httpx' ")

from rich.json import JSON

from textual.app import App, ComposeResult
from textual.containers import VerticalScroll
from textual.widgets import Input, Static


class DictionaryApp(App):
    """Searches a dictionary API as-you-type."""

    CSS_PATH = "dictionary.tcss"

    def compose(self) -> ComposeResult:
        yield Input(placeholder="Search for a word")
        yield VerticalScroll(Static(id="results"), id="results-container")

    async def on_input_changed(self, message: Input.Changed) -> None:
        """A coroutine to handle a text changed message."""
        if message.value:
            # Look up the word in the background
            asyncio.create_task(self.lookup_word(message.value))
        else:
            # Clear the results
            self.query_one("#results", Static).update()

    async def lookup_word(self, word: str) -> None:
        """Looks up a word."""
        url = f"https://api.dictionaryapi.dev/api/v2/entries/en/{word}"
        async with httpx.AsyncClient() as client:
            results = (await client.get(url)).text

        if word == self.query_one(Input).value:
            self.query_one("#results", Static).update(JSON(results))


if __name__ == "__main__":
    app = DictionaryApp()
    app.run()

```

```css
Screen {
    background: $panel;
}

Input {
    dock: top;
    width: 100%;
    height: 1;
    padding: 0 1;
    margin: 1 1 0 1;
}

#results {
    width: auto;
    min-height: 100%;
}

#results-container {
    background: $background 50%;
    overflow: auto;
    margin: 1 2;
    height: 100%;
}

```

--------------------------------

### Complete App Example with Funding Progress (progress_bar.py)

Source: https://textual.textualize.io/widgets/progress_bar

A simple app with a progress bar tracking a fictitious funding level. Includes an input for donations and a button to donate.

```python
from textual.app import App, ComposeResult
from textual.containers import Center, VerticalScroll
from textual.widgets import Button, Header, Input, Label, ProgressBar


class FundingProgressApp(App[None]):
    CSS_PATH = "progress_bar.tcss"

    TITLE = "Funding tracking"

    def compose(self) -> ComposeResult:
        yield Header()
        with Center():
            yield Label("Funding: ")
            yield ProgressBar(total=100, show_eta=False)  
        with Center():
            yield Input(placeholder="$$$")
            yield Button("Donate")

        yield VerticalScroll(id="history")

    def on_button_pressed(self) -> None:
        self.add_donation()

    def on_input_submitted(self) -> None:
        self.add_donation()

    def add_donation(self) -> None:
        text_value = self.query_one(Input).value
        try:
            value = int(text_value)
        except ValueError:
            return
        self.query_one(ProgressBar).advance(value)
        self.query_one(VerticalScroll).mount(Label(f"Donation for ${value} received!"))
        self.query_one(Input).value = ""


if __name__ == "__main__":
    FundingProgressApp().run()
```

--------------------------------

### Python API examples

Source: https://textual.textualize.io/styles/links/link_background

Shows how to set `link-background` from Python using a string or a `Color` object.

```python
widget.styles.link_background = "red 70%"
widget.styles.link_background = "$accent"

# You can also use a `Color` object directly:
widget.styles.link_background = Color(100, 30, 173)

```

--------------------------------

### stopwatch02.py: Custom widgets and app composition

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

This is the main code example for the stopwatch app. It defines a TimeDisplay widget extending Digits, a Stopwatch widget extending HorizontalGroup with Start, Stop, Reset buttons and a time display, and a StopwatchApp with a VerticalScroll containing three stopwatches. It also includes a dark mode toggle binding.

```python
from textual.app import App, ComposeResult
from textual.containers import HorizontalGroup, VerticalScroll
from textual.widgets import Button, Digits, Footer, Header


class TimeDisplay(Digits):
    """A widget to display elapsed time."""


class Stopwatch(HorizontalGroup):
    """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")


class StopwatchApp(App):
    """A Textual app to manage stopwatches."""

    BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]

    def compose(self) -> ComposeResult:
        """Create child widgets for the app."""
        yield Header()
        yield Footer()
        yield VerticalScroll(Stopwatch(), Stopwatch(), Stopwatch())

    def action_toggle_dark(self) -> None:
        """An action to toggle dark mode."""
        self.theme = (
            "textual-dark" if self.theme == "textual-light" else "textual-light"
        )


if __name__ == "__main__":
    app = StopwatchApp()
    app.run()
```

--------------------------------

### watch method example

Source: https://textual.textualize.io/api/dom_node

Example of using watch to monitor changes to app.theme. The callback prints the old and new values. init=False prevents an immediate check.

```python
def on_theme_change(old_value:str, new_value:str) -> None:
    # Called when app.theme changes.
    print(f"App.theme went from {old_value} to {new_value}")

self.watch(self.app, "theme", self.on_theme_change, init=False)
```

--------------------------------

### notify usage examples

Source: https://textual.textualize.io/api/app

Examples of using the notify method with different severities and options. The warning example uses Rich console markup. The error example sets a longer timeout. The final example shows an information notification with an empty title.

```python
# Show an information notification.
self.notify("It's an older code, sir, but it checks out.")

# Show a warning. Note that Textual's notification system allows
# for the use of Rich console markup.
self.notify(
    "Now witness the firepower of this fully "
    "[b]ARMED[/b] and [i][b]OPERATIONAL[/b][/i] battle station!",
    title="Possible trap detected",
    severity="warning",
)

# Show an error. Set a longer timeout so it's noticed.
self.notify("It's a trap!", severity="error", timeout=10)

# Show an information notification, but without any sort of title.
self.notify("It's against my programming to impersonate a deity.", title="")

```

--------------------------------

### stopwatch04.tcss: CSS for stopwatch with started state

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

CSS styles for the Stopwatch widget, including base styles and a .started class that changes the background, hides the start button, shows the stop button, and hides the reset button. The .started #start rule hides the start button only when inside a container with the started class.

```css
Stopwatch {
    background: $boost;
    height: 5;
    margin: 1;
    min-width: 50;
    padding: 1;
}

TimeDisplay {   
    text-align: center;
    color: $foreground-muted;
    height: 3;
}

Button {
    width: 16;
}

#start {
    dock: left;
}

#stop {
    dock: left;
    display: none;
}

#reset {
    dock: right;
}

.started {
    background: $success-muted;
    color: $text;
}

.started TimeDisplay {
    color: $foreground;
}

.started #start {
    display: none
}

.started #stop {
    display: block
}

.started #reset {
    visibility: hidden
}
```

--------------------------------

### on_button_pressed event handler

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

Handles button presses for start, stop, and reset buttons. It queries the TimeDisplay widget and calls its start, stop, or reset methods accordingly, and adds or removes the 'started' class for start and stop actions.

```python
    def on_button_pressed(self, event: Button.Pressed) -> None:
        """Event handler called when a button is pressed."""
        button_id = event.button.id
        time_display = self.query_one(TimeDisplay)
        if button_id == "start":
            time_display.start()
            self.add_class("started")
        elif button_id == "stop":
            time_display.stop()
            self.remove_class("started")
        elif button_id == "reset":
            time_display.reset()

```

--------------------------------

### Toast Example Application

Source: https://textual.textualize.io/widgets/toast

Example application demonstrating the notify method with different severities and options. Shows how to display information, warning, and error notifications, and how to omit the title.

```python
from textual.app import App


class ToastApp(App[None]):
    def on_mount(self) -> None:
        # Show an information notification.
        self.notify("It's an older code, sir, but it checks out.")

        # Show a warning. Note that Textual's notification system allows
        # for the use of Rich console markup.
        self.notify(
            "Now witness the firepower of this fully "
            "[b]ARMED[/b] and [i][b]OPERATIONAL[/b][/i] battle station!",
            title="Possible trap detected",
            severity="warning",
        )

        # Show an error. Set a longer timeout so it's noticed.
        self.notify("It's a trap!", severity="error", timeout=10)

        # Show an information notification, but without any sort of title.
        self.notify("It's against my programming to impersonate a deity.", title="")


if __name__ == "__main__":
    ToastApp().run()
```

--------------------------------

### delete(start, end)

Source: https://textual.textualize.io/widgets/input

Deletes the text between the start and end locations.

```APIDOC
## delete(start, end)

### Description
Delete the text between the start and end locations.

### Method
delete

### Signature
```
delete(start, end)
```

### Parameters
- **start** (int) - Required - Start index to delete (inclusive).
- **end** (int) - Required - End index to delete (inclusive).

### Returns
None
```

--------------------------------

### display example

Source: https://textual.textualize.io/api/dom_node

Example of hiding a widget by setting display to False.

```python
my_widget.display = False  # Hide my_widget

```

--------------------------------

### css_tree example

Source: https://textual.textualize.io/api/dom_node

Example of logging the css_tree property to visualize the DOM.

```python
self.log(self.css_tree)

```

--------------------------------

### Serve an app from a Python file

Source: https://textual.textualize.io/guide/devtools

Use `textual serve` to serve an app launched from a Python file. The app will be available in a browser.

```bash
textual serve my_app.py
```

--------------------------------

### Example: Using SuggestFromList with Input widget

Source: https://textual.textualize.io/api/suggester

Example showing how to use SuggestFromList with an Input widget. If the user types 'P', a suggestion for 'Portugal' appears.

```python
countries = ["England", "Scotland", "Portugal", "Spain", "France"]

class MyApp(App[None]):
    def compose(self) -> ComposeResult:
        yield Input(suggester=SuggestFromList(countries, case_sensitive=False))
```

--------------------------------

### Serve an app launched via a command

Source: https://textual.textualize.io/guide/devtools

Use `textual serve` with a command string to serve an app launched via a command, such as `textual keys`.

```bash
textual serve "textual keys"
```

--------------------------------

### Install project in editable mode

Source: https://textual.textualize.io/how-to/package-with-hatch

Installs the project in editable mode so pip won't copy the .py files. The dot indicates installing the project in the current directory.

```bash
pip install -e .

```

--------------------------------

### get_text_range(start, end)

Source: https://textual.textualize.io/widgets/text_area

Retrieves the text between a start and end location in the document.

```APIDOC
## get_text_range(start, end)

### Description
Get the text between a start and end location.

### Method
get_text_range

### Parameters
- **start** (Location) - Required - The start location.
- **end** (Location) - Required - The end location.

### Returns
- **str** - The text between start and end.
```

--------------------------------

### set_timer example with ready callback

Source: https://textual.textualize.io/api/message_pump

Example showing how to use set_timer to call a method after a delay. Defines a ready method that notifies the user, then schedules it after 3 minutes.

```python
def ready():
    self.notify("Your soft boiled egg is ready!")
# Call ready() after 3 minutes
self.set_timer(3 * 60, ready)

```

--------------------------------

### Examples of using the log function

Source: https://textual.textualize.io/guide/devtools

Shows how to log strings, local variables, key/value pairs, and Rich renderables using the `log` function.

```python
def on_mount(self) -> None:
    log("Hello, World")  # simple string
    log(locals())  # Log local variables
    log(children=self.children, pi=3.141592)  # key/values
    log(self.tree)  # Rich renderables

```

--------------------------------

### set_reactive usage example

Source: https://textual.textualize.io/api/dom_node

Example showing how to set a reactive value directly.

```python
self.set_reactive(App.theme, "textual-light")
```

--------------------------------

### Install Textual from PyPI

Source: https://textual.textualize.io/getting_started

Installs the Textual package from PyPI using pip.

```bash
pip install textual
```

--------------------------------

### Footer example app

Source: https://textual.textualize.io/widgets/footer

An example app with a Footer widget and several keybindings. The Footer automatically displays the keybindings. Note that bindings with show=False are hidden from the footer, and key_display customizes the displayed key text.

```python
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.widgets import Footer


class FooterApp(App):
    BINDINGS = [
        Binding(key="q", action="quit", description="Quit the app"),
        Binding(
            key="question_mark",
            action="help",
            description="Show help screen",
            key_display="?",
        ),
        Binding(key="delete", action="delete", description="Delete the thing"),
        Binding(key="j", action="down", description="Scroll down", show=False),
    ]

    def compose(self) -> ComposeResult:
        yield Footer()


if __name__ == "__main__":
    app = FooterApp()
    app.run()
```

--------------------------------

### Install syntax highlighting dependencies with poetry

Source: https://textual.textualize.io/widgets/text_area

Install the 'syntax' extra dependencies for TextArea syntax highlighting using poetry. This installs tree-sitter and tree-sitter-languages, which are distributed as binary wheels and may limit environments where they are available.

```bash
poetry add "textual[syntax]"

```

--------------------------------

### CSS border examples

Source: https://textual.textualize.io/css_types/border

CSS examples showing how to set a heavy red border on a container and a solid blue bottom border on a heading.

```css
#container {
    border: heavy red;
}

#heading {
    border-bottom: solid blue;
}

```
Tokens:
Raw