TITLE: Styling a Header Widget with Basic CSS in Textual
DESCRIPTION: This CSS rule set defines styles for a `Header` widget in Textual. It docks the header to the top, sets its height to 3 units, aligns content to the center and middle, and applies a blue background with white text. This demonstrates a complete CSS rule set for a specific widget.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_0

LANGUAGE: css
CODE:
```
Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}
```

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

TITLE: Implement Clickable Text Links in Textual Widgets
DESCRIPTION: Demonstrates how to create clickable text links within Textual widgets using special markup. The example shows how to define a click handler that triggers an application action (e.g., `app.bell`) when the link is activated, allowing for interactive text elements.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_4

LANGUAGE: markup
CODE:
```
"Click [@click=app.bell]Me[/]"
```

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/hello05.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/widgets/hello05.tcss"
```

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

TITLE: Textual TextArea Widget API Reference
DESCRIPTION: Comprehensive API documentation for the Textual TextArea widget, detailing its constructor, properties, and methods for text editing, selection, and cursor management. This reference outlines how to interact with the TextArea programmatically.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/text_area.md#_snippet_3

LANGUAGE: APIDOC
CODE:
```
TextArea:
  Description: A widget for editing text which may span multiple lines. Supports text selection, soft wrapping, optional syntax highlighting with tree-sitter and a variety of keybindings.
  Properties:
    focusable: boolean (true)
    container: boolean (false)
    language: str (reactive)
      Description: Sets the language for syntax highlighting.
    text: str
      Description: Returns all content in the text area as a string. Can be set to update content programmatically.
    selected_text: str
      Description: Returns the text corresponding to the current selection.
    cursor_location: tuple (row_index, column_index)
      Description: Represents the location of the cursor as a zero-based tuple (row_index, column_index). Can be read or set to move the cursor.
    document.end: tuple (row_index, column_index)
      Description: Returns the location at the end of the document.
  Methods:
    code_editor():
      Description: Convenience constructor. Returns a new TextArea with soft-wrapping disabled, line numbers enabled, and tab key behavior configured to insert '\t'.
    get_text_range(start_location: tuple, end_location: tuple):
      Description: Returns the text between two locations.
      Parameters:
        start_location: (row_index, column_index) - The starting position.
        end_location: (row_index, column_index) - The ending position.
      Returns: str - The text content.
    replace(start_location: tuple, end_location: tuple, new_text: str):
      Description: Programmatic equivalent of selecting text and pasting.
      Parameters:
        start_location: (row_index, column_index) - The starting position for replacement.
        end_location: (row_index, column_index) - The ending position for replacement.
        new_text: str - The text to insert.
    insert(location: tuple, text: str):
      Description: Inserts text at a specific location.
      Parameters:
        location: (row_index, column_index) - The insertion point.
        text: str - The text to insert.
    delete(start_location: tuple, end_location: tuple):
      Description: Deletes text within a specified range.
      Parameters:
        start_location: (row_index, column_index) - The starting position for deletion.
        end_location: (row_index, column_index) - The ending position for deletion.
    clear():
      Description: Clears all content from the TextArea.
```

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

TITLE: Python Key Binding Definition Example
DESCRIPTION: Illustrates how to define key bindings in a Textual application using the `BINDINGS` class variable. This example shows binding 'r', 'g', and 'b' keys to an action that adds a bar widget to the screen.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/input.md#_snippet_5

LANGUAGE: Python
CODE:
```
--8<-- "docs/examples/guide/input/binding01.py"
```

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

TITLE: Textual BitSwitch to ByteEditor Communication (Messages Up)
DESCRIPTION: Demonstrates how a `BitSwitch` widget sends a custom `BitSwitch.BitChanged` message to its parent `ByteEditor` when its state changes. The `ByteEditor` then processes this message to update a decimal value. It also shows how to handle the built-in `Switch.Changed` event and stop its propagation to prevent unintended parent reactions.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_26

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/compound/byte02.py"
```

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

TITLE: CSS Styling for Checkbox Widget Example
DESCRIPTION: CSS (TCSS) styling for the Checkbox widget example, included from an external file.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/checkbox.md#_snippet_2

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/widgets/checkbox.tcss"
```

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

TITLE: Example Usage of RadioButton in Python
DESCRIPTION: Demonstrates how to use the RadioButton widget within a Textual application, typically inside a RadioSet, by referencing an external Python file.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/radiobutton.md#_snippet_0

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/widgets/radio_button.py"
```

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

TITLE: Use Auto-closing Tag for Markup Styles
DESCRIPTION: Illustrates the use of an auto-closing tag (`[/]`) to end the last opened style. This provides a convenient shorthand for closing tags when the context is clear, reducing verbosity while maintaining functionality.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_5

LANGUAGE: Textual Markup
CODE:
```
[bold]Hello[/], World!
```

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

TITLE: Textual Key Event Attributes (APIDOC)
DESCRIPTION: Documents the attributes of the `Key` event object in Textual, which are sent when a user presses a key. These attributes provide detailed information about the pressed key, including its identifier, printable character, normalized name, printability, and aliases.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/input.md#_snippet_1

LANGUAGE: APIDOC
CODE:
```
Key Event Attributes:
  key: string
    Description: Identifies the key pressed. Single character for letters/numbers, longer identifier for others. Prefixed with 'shift+' or 'ctrl+' for combinations.
  character: string | None
    Description: Contains a single Unicode character if the key has an associated printable character; otherwise, None.
  name: string
    Description: A Python-valid function name derived from 'key'. Lowercased, '+' replaced with '_'. Uppercase letters prefixed with 'upper_'.
  is_printable: boolean
    Description: Indicates if the key would typically result in something usable in an input widget (e.g., a character). False for control codes or function keys.
  aliases: list[string]
    Description: A list of possible keys that may have produced this event, for keys or combinations that are indistinguishable (e.g., "tab" and "ctrl+i").
```

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

TITLE: Textual `on` Decorator with Message Attribute Matching
DESCRIPTION: This example demonstrates the advanced usage of Textual's `@on` decorator, allowing it to match messages based on specific attributes using keyword arguments like `pane="#home"`. This enables highly granular control over which messages a handler responds to, beyond just the event type.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/events.md#_snippet_3

LANGUAGE: python
CODE:
```
@on(TabbedContent.TabActivated, pane="#home")
def home_tab(self) -> None:
    self.log("Switched back to home tab.")
    ...
```

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

TITLE: Styling Textual Button on Hover (CSS Pseudo-class)
DESCRIPTION: Shows how to use the `:hover` pseudo-class to change the background color of a Textual `Button` to green when the mouse cursor is over it. This enables dynamic styling based on widget states.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_15

LANGUAGE: css
CODE:
```
Button:hover {
  background: green;
}
```

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

TITLE: Textual: Mounting Widgets Without Await (Problem)
DESCRIPTION: Illustrates a common pitfall when dynamically adding widgets in Textual. Attempting to query a newly mounted widget immediately after calling `mount()` can lead to a `NoMatches` exception because the mounting process is not yet complete. This example shows the incorrect approach.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/app.md#_snippet_5

LANGUAGE: python
CODE:
```
from textual.app import App
from textual.widgets import Button, Welcome


class WelcomeApp(App):
    def on_key(self) -> None:
        self.mount(Welcome())
        self.query_one(Button).label = "YES!" # (1)!


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

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

TITLE: Python Textual Widget scrollbar_gutter Style Examples
DESCRIPTION: Demonstrates how to programmatically set the `scrollbar_gutter` style property on a Textual widget's styles object in Python, mirroring the CSS functionality to control scrollbar space reservation.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/scrollbar_gutter.md#_snippet_2

LANGUAGE: python
CODE:
```
self.styles.scrollbar_gutter = "auto"    # Don't reserve space for a vertical scrollbar.
self.styles.scrollbar_gutter = "stable"  # Reserve space for a vertical scrollbar.
```

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

TITLE: Create Clickable Links in Textual Markup
DESCRIPTION: Shows how to embed clickable hyperlinks within Textual applications using the `link=` attribute in markup. These links are designed to open in the user's web browser if supported by the terminal environment.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_15

LANGUAGE: Textual Markup
CODE:
```
[link="https://www.willmcgugan.com"]Visit my blog![/link]
```

LANGUAGE: HTML
CODE:
```
<code><pre><a href="https://www.willmcgugan.com">Visit my blog!</a></pre></code>
```

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

TITLE: Implement a Fixed Sidebar with Textual Docking
DESCRIPTION: This example demonstrates how to create a simple Textual application with a sidebar that is docked to the left edge of the screen. The sidebar remains visible even when the main content area scrolls, making it suitable for navigation or persistent information.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/layout.md#_snippet_8

LANGUAGE: python
CODE:
```
from textual.app import App, ComposeResult
from textual.widgets import Static
from textual.containers import Container, ScrollView

class DockingApp(App):
    CSS_PATH = "dock_layout1_sidebar.tcss"

    def compose(self) -> ComposeResult:
        yield Container(Static("This is a sidebar"), id="sidebar")
        yield ScrollView(Static("Lorem ipsum dolor sit amet, consectetur adipiscing elit. " * 100), id="body")

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

LANGUAGE: css
CODE:
```
#sidebar {
    dock: left;
    width: 20%;
    background: $panel;
}
#body {
    background: $surface;
}
```

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

TITLE: Textual Input Widget Validation on Submission
DESCRIPTION: Shows how to configure the `Input` widget to trigger validation only when the value is explicitly submitted, using the `validate_on` parameter.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/input.md#_snippet_2

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

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

TITLE: Apply CSS Variables in Textual Markup
DESCRIPTION: Demonstrates how to use predefined CSS variables (e.g., `$accent`, `$warning`, `$warning-muted`) directly within Textual's rich markup to style text and backgrounds. This allows for consistent theming based on the application's design guide.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_14

LANGUAGE: Textual Markup
CODE:
```
[$accent]Accent color[/]
```

LANGUAGE: Textual Markup
CODE:
```
[$warning on $warning-muted]This is a warning![/]
```

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

TITLE: Escape Markup Tags and Disable Markup Processing
DESCRIPTION: Illustrates two methods for handling markup: preventing Textual from interpreting square brackets as tags by preceding them with a backslash, and disabling markup processing entirely for specific output methods like `notify()` in Python, useful for displaying raw strings.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_17

LANGUAGE: Textual Markup
CODE:
```
\[bold]This is not bold
```

LANGUAGE: Python
CODE:
```
self.notify(repr(my_list), markup=False)
```

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

TITLE: Styling All Children of a Parent Widget (Textual CSS)
DESCRIPTION: Demonstrates how to use the universal selector in combination with a parent selector (`VerticalScroll *`) to apply a red background to all child widgets within a `VerticalScroll` container in Textual CSS.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_14

LANGUAGE: css
CODE:
```
VerticalScroll * {
  background: red;
}
```

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

TITLE: Applying Universal Selector in Textual CSS
DESCRIPTION: Illustrates the universal selector (`*`) in Textual CSS, which applies a red solid outline to all widgets in the application. This selector is useful for global styling or debugging.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_13

LANGUAGE: css
CODE:
```
* {
  outline: solid red;
}
```

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

TITLE: Textual Python Widget Padding Assignment
DESCRIPTION: Demonstrates how to set padding for a Textual widget's styles in Python. It shows assigning a single integer for all edges, a tuple of two integers for vertical/horizontal padding, and a tuple of four integers for individual edge padding.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/padding.md#_snippet_2

LANGUAGE: python
CODE:
```
# Set padding of 1 around all edges
widget.styles.padding = 1
# Set padding of 2 on the top and bottom edges, and 4 on the left and right
widget.styles.padding = (2, 4)
# Set padding of 1 on top, 2 on the right, 3 on the bottom, and 4 on the left
widget.styles.padding = (1, 2, 3, 4)
```

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

TITLE: Handle User Input Submission Event
DESCRIPTION: The `on_input` method is an event handler triggered when the user submits text in the `Input` widget (e.g., by pressing Enter). It clears the input field, adds the user's prompt to the chat view, mounts a new `Response` widget to display the LLM's reply, anchors it to the bottom of the scrollable view, and then calls `send_prompt` to process the input.
SOURCE: https://github.com/textualize/textual/blob/main/docs/blog/posts/anatomy-of-a-textual-user-interface.md#_snippet_6

LANGUAGE: python
CODE:
```
    @on(Input.Submitted)
    async def on_input(self, event: Input.Submitted) -> None:
        chat_view = self.query_one("#chat-view")
        event.input.clear()
        await chat_view.mount(Prompt(event.value))
        await chat_view.mount(response := Response())
        response.anchor()
        self.send_prompt(event.value, response)
```

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

TITLE: Set Widget Opacity in CSS
DESCRIPTION: Demonstrates how to set the `opacity` of a Textual widget using CSS, fading it to 50% transparency against its parent's background.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/opacity.md#_snippet_1

LANGUAGE: css
CODE:
```
/* Fade the widget to 50% against its parent's background */
opacity: 50%;
```

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

TITLE: Set Text Style using Python Styles API
DESCRIPTION: A Python code snippet illustrating how to programmatically set the `text_style` property of a Textual widget. This method allows for dynamic styling of text within a Textual application using Python code.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_style.md#_snippet_4

LANGUAGE: Python
CODE:
```
widget.styles.text_style = "italic"
```

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

TITLE: Apply grid-columns Style in Textual CSS and Python
DESCRIPTION: Examples demonstrating how to set the `grid-columns` property using both CSS and Python. This allows developers to define column widths using percentages, fractional units (fr), or fixed values, controlling the layout of a Textual grid.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/grid/grid_columns.md#_snippet_1

LANGUAGE: css
CODE:
```
/* Set all columns to have 50% width */
grid-columns: 50%;

/* Every other column is twice as wide as the first one */
grid-columns: 1fr 2fr;
```

LANGUAGE: py
CODE:
```
grid.styles.grid_columns = "50%"
grid.styles.grid_columns = "1fr 2fr"
```

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

TITLE: Improved Modal Dialog with ModalScreen (modal02)
DESCRIPTION: Illustrates an improved modal dialog using `ModalScreen`. This specialized screen subclass automatically prevents app-level key bindings from being processed while active and sets a semi-transparent background to visually indicate that the main interface is temporarily disabled.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/screens.md#_snippet_3

LANGUAGE: Python
CODE:
```
from textual.app import App, Screen, ComposeResult
from textual.widgets import Header, Footer, Button, Label, VerticalScroll
from textual.containers import Container
from textual.screen import ModalScreen # Highlighted line 3

class QuitScreen(ModalScreen): # Highlighted line 15
    BINDINGS = [
        ("escape", "app.pop_screen", "Cancel"),
        ("q", "quit_app", "Quit"),
    ]

    def compose(self) -> ComposeResult:
        yield Container(
            Label("Are you sure you want to quit?"),
            Button("Quit", id="quit_button", variant="error"),
            Button("Cancel", id="cancel_button"),
            id="quit_dialog"
        )

    def on_button_pressed(self, event: Button.Pressed) -> None:
        if event.button.id == "quit_button":
            self.app.exit()
        elif event.button.id == "cancel_button":
            self.app.pop_screen()

class MainScreen(Screen):
    def compose(self) -> ComposeResult:
        yield Header()
        yield VerticalScroll(
            Label("This is the main application screen. Press 'q' to quit.")
        )
        yield Footer()

class MyApp(App):
    SCREENS = {"main": MainScreen()}
    BINDINGS = [
        ("q", "request_quit", "Quit App"),
    ]

    def on_mount(self) -> None:
        self.push_screen("main")

    def action_request_quit(self) -> None:
        self.push_screen(QuitScreen())

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

LANGUAGE: CSS
CODE:
```
#quit_dialog {
    background: $panel;
    border: thick $accent;
    padding: 2 4;
    width: 50%;
    height: auto;
    align: center middle;
    layout: vertical;
}
#quit_dialog Label {
    margin-bottom: 1;
}
#quit_dialog Button {
    width: 100%;
    margin-top: 1;
}
```

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

TITLE: Style a Custom Textual Widget with External CSS
DESCRIPTION: This example illustrates how to apply external CSS to a custom Textual widget. It shows a Python application that uses a custom widget and an accompanying CSS file to dramatically transform the widget's visual appearance, demonstrating the power of external styling.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_1

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/hello02.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/widgets/hello02.tcss"
```

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

TITLE: Enable Focus and Basic Keybindings for Textual Widgets
DESCRIPTION: Shows how to make a Textual widget focusable by setting `can_focus=True` in its class definition. This allows the widget to receive keyboard input and respond to user interactions. The example demonstrates a simple focusable counter widget that can be selected.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_6

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/counter01.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/widgets/counter.tcss"
```

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

TITLE: Add Advanced Keybindings and Actions to Textual Widgets
DESCRIPTION: Expands on widget focus by adding custom keybindings to a Textual widget. This example demonstrates how to associate specific key presses (e.g., 'up', 'down') with custom actions defined within the widget, allowing interactive control of widget attributes like a counter's value based on keyboard input.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_7

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/counter02.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/widgets/counter.tcss"
```

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

TITLE: Including External Code for Display with Rich Syntax
DESCRIPTION: This directive, common in Textual's documentation, indicates the inclusion of an external Python file (`renderables.py`) for display. It's used to demonstrate how Textual can render code using Rich's `Syntax` object, effectively displaying source code within the application.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_24

LANGUAGE: textual-doc-directive
CODE:
```
--8<-- "docs/examples/guide/content/renderables.py"
```

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

TITLE: Define Basic Reactive Attributes in Textual
DESCRIPTION: Illustrates how to create simple reactive attributes (string, integer, boolean) with default values using `textual.reactive.reactive` within a Textual Widget class. These attributes do not require definition in the `__init__` method.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/reactivity.md#_snippet_0

LANGUAGE: python
CODE:
```
from textual.reactive import reactive
from textual.widget import Widget

class Reactive(Widget):

    name = reactive("Paul")
    count = reactive(0)
    is_cool = reactive(True)
```

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

TITLE: Safely Embedding Variables in Textual Markup with Content.from_markup
DESCRIPTION: This example shows the recommended method for inserting variables into Textual markup using `Content.from_markup`. By passing variables as keyword arguments, it ensures that any square brackets in the variable content are treated as literal text, preventing markup interpretation issues.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_22

LANGUAGE: python
CODE:
```
return Content.from_markup("hello [bold]$name[/bold]!", name=name)
```

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

TITLE: Keyline CSS Property Syntax
DESCRIPTION: Defines the syntax for the `keyline` CSS property, specifying its allowed values for keyline style (e.g., thin, thick) and color.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/keyline.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
keyline: [<keyline>] [<color>];
```

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

TITLE: Textual Python Widget `visible` Property Shortcut
DESCRIPTION: Illustrates a convenient shortcut for setting a Textual widget's visibility using the boolean `widget.visible` property, where `False` hides the widget and `True` makes it visible.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/visibility.md#_snippet_3

LANGUAGE: Python
CODE:
```
# Make a widget invisible
widget.visible = False

# Make the widget visible again
widget.visible = True
```

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

TITLE: Retrieve Single Widget by Type with query_one
DESCRIPTION: Illustrates using `self.query_one()` to find a single widget of a specific type. This method assumes there is only one such widget within the search scope and returns its instance.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/queries.md#_snippet_2

LANGUAGE: python
CODE:
```
my_button = self.query_one(Button)
```

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

TITLE: Using Textual HorizontalGroup for Compact Widget Arrangement
DESCRIPTION: This example showcases the `HorizontalGroup` container, which differs from `Horizontal` by not expanding to fill the screen. Instead, it only occupies the necessary space to fit its content, making it ideal for creating tightly packed rows of widgets.
SOURCE: https://github.com/textualize/textual/blob/main/docs/how-to/work-with-containers.md#_snippet_5

LANGUAGE: Python
CODE:
```
--8<-- "docs/examples/how-to/containers05.py"
```

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

TITLE: Applying a Border to a Textual Widget
DESCRIPTION: Demonstrates how to add a border to a Textual widget by setting the `styles.border` property. The border requires a type (string) and a color value. This example references an external Python file for the full implementation.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/styles.md#_snippet_4

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/styles/border01.py"
```

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

TITLE: Textual Input Widget Reactive Attributes
DESCRIPTION: Describes the reactive attributes available for the Textual Input widget, including their types, default values, and descriptions. These attributes control the behavior and appearance of the input field.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/input.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
Input Widget Reactive Attributes:
  cursor_blink:
    Type: bool
    Default: True
    Description: True if cursor blinking is enabled.
  value:
    Type: str
    Default: ""
    Description: The value currently in the text input.
  cursor_position:
    Type: int
    Default: 0
    Description: The index of the cursor in the value string.
  placeholder:
    Type: str
    Default: ""
    Description: The dimmed placeholder text to display when the input is empty.
  password:
    Type: bool
    Default: False
    Description: True if the input should be masked.
  restrict:
    Type: str
    Default: None
    Description: Optional regular expression to restrict input.
  type:
    Type: str
    Default: "text"
    Description: The type of the input.
  max_length:
    Type: int
    Default: None
    Description: Maximum length of the input value.
  valid_empty:
    Type: bool
    Default: False
    Description: Allow empty values to bypass validation.
```

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

TITLE: Styling Textual Widget with Single Class Selector (CSS)
DESCRIPTION: Defines a CSS rule that targets Textual widgets with the 'success' class. It sets the background color to green and text color to white, demonstrating how to apply styles based on a single class name.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_11

LANGUAGE: css
CODE:
```
.success {
  background: green;
  color: white;
}
```

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

TITLE: Applying CSS Rules to Textual Widgets
DESCRIPTION: This CSS snippet focuses on the individual rules within a rule set. Each line inside the curly braces, like `dock: top;` or `background: blue;`, represents a CSS rule consisting of a property name and a value. These rules define specific visual and layout properties for the `Header` widget, such as its position, size, alignment, and colors.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_2

LANGUAGE: css
CODE:
```
Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}
```

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

TITLE: Textual `Strip` Object
DESCRIPTION: The `Strip` object in Textual acts as a container for one or more `Segment` objects, representing a complete single line (or row) of content within a widget. It is constructed from a list of `Segment`s and can optionally include an explicit `cell_length` for precise layout control, especially important for characters occupying multiple terminal cells.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_11

LANGUAGE: APIDOC
CODE:
```
Strip:
  __init__(segments: list[Segment], cell_length: int = None)
    segments: A list of `Segment` objects that compose the line.
    cell_length: Optional integer, the total number of terminal cells the strip occupies. If omitted, Textual calculates it automatically.
```

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

TITLE: Textual Mouse Events and Widget Methods API Reference
DESCRIPTION: This section provides an API reference for various mouse-related events and widget methods available in Textual. It covers events for mouse movement, capture, entry/exit, button presses, clicks, and scrolling, as well as methods for controlling mouse event propagation.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/input.md#_snippet_10

LANGUAGE: APIDOC
CODE:
```
Textual Events:
  - MouseMove: Event containing mouse coordinates and modifier keys (ctrl, shift, etc.).
  - MouseCapture: Event sent to a widget when it captures the mouse.
  - MouseRelease: Event sent to a widget when mouse capture is released.
  - Enter: Event sent to a widget when the mouse cursor first moves over it.
  - Leave: Event sent to a widget when the mouse cursor moves off it.
  - MouseDown: Event sent when a mouse button is initially pressed.
  - MouseUp: Event sent when a mouse button is released.
  - Click: Event sent after MouseDown and MouseUp; preferred for responding to mouse clicks.
  - MouseScrollDown: Event sent when the scroll wheel scrolls down.
  - MouseScrollUp: Event sent when the scroll wheel scrolls up.

Textual Widget Methods:
  - capture_mouse(): Makes a widget receive all mouse events regardless of cursor position.
  - release_mouse(): Restores the default mouse event handling behavior for a widget.

Textual Styles:
  - offset: A style property (e.g., for `ball` widget) used to set its position relative to its parent.
```

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

TITLE: Set Column-span Programmatically in Python
DESCRIPTION: Illustrates how to programmatically set the `column-span` style for a Textual widget using Python, by assigning an integer value to the `styles.column_span` attribute.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/grid/column_span.md#_snippet_2

LANGUAGE: Python
CODE:
```
widget.styles.column_span = 3
```

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

TITLE: Define TabbedContent Panes with IDs for Programmatic Switching
DESCRIPTION: Shows how to assign unique 'id' attributes to TabPane widgets. These IDs are crucial for programmatically controlling which tab is active, allowing direct referencing of specific content panes.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/tabbed_content.md#_snippet_2

LANGUAGE: python
CODE:
```
def compose(self) -> ComposeResult:
    with TabbedContent():
        with TabPane("Leto", id="leto"):
            yield Markdown(LETO)
        with TabPane("Jessica", id="jessica"):
            yield Markdown(JESSICA)
        with TabPane("Paul", id="paul"):
            yield Markdown(PAUL)
```

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

TITLE: Content Alignment CSS Property Usage Examples
DESCRIPTION: Demonstrates various ways to use `content-align`, `content-align-horizontal`, and `content-align-vertical` CSS properties to control content alignment within a Textual widget. Examples include centering content and aligning to specific corners or edges.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/content_align.md#_snippet_1

LANGUAGE: css
CODE:
```
/* Align content in the very center of a widget */
content-align: center middle;
/* Align content at the top right of a widget */
content-align: right top;

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

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

TITLE: DirectoryTree Reactive Attributes
DESCRIPTION: Defines the configurable reactive attributes of the DirectoryTree widget, controlling its display and behavior.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/directory_tree.md#_snippet_2

LANGUAGE: APIDOC
CODE:
```
show_root: bool = True
  Description: Show the root node.
show_guides: bool = True
  Description: Show guide lines between levels.
guide_depth: int = 4
  Description: Amount of indentation between parent and child.
```

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

TITLE: Python Background Tint Style Assignment
DESCRIPTION: Illustrates how to programmatically set the `background-tint` style for a Textual widget in Python. Examples include assigning a string value (similar to CSS) and using a `textual.color.Color` object for more precise control over the tint color and opacity.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/background_tint.md#_snippet_3

LANGUAGE: python
CODE:
```
# Set 20% blue background tint
widget.styles.background_tint = "blue 20%"

from textual.color import Color
# Set with a color object
widget.styles.background_tint = Color(120, 60, 100, 0.5)
```

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

TITLE: Centering multiple widgets as a group using parent alignment in Textual
DESCRIPTION: Illustrates how to center a group of widgets within their parent container by applying the `align: center middle;` CSS rule to the parent. This method aligns the entire group without changing the relative positions of the widgets within the group.
SOURCE: https://github.com/textualize/textual/blob/main/docs/how-to/center-things.md#_snippet_1

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/how-to/center09.py"
```

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

TITLE: Defining a CSS Selector for Textual Widgets
DESCRIPTION: This CSS snippet highlights the selector part of a rule set. The `Header` selector targets widgets of the `Header` Python class, indicating that the enclosed styles will be applied to instances of this specific widget type. It's the first part of a CSS rule set that determines which elements are affected.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_1

LANGUAGE: css
CODE:
```
Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}
```

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

TITLE: Start Textual Debug Console
DESCRIPTION: Launches the Textual debug console in a separate terminal, which captures `print` statements and log messages from Textual applications running in development mode.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/devtools.md#_snippet_11

LANGUAGE: bash
CODE:
```
textual console
```

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

TITLE: CSS text-align Property Syntax Definition
DESCRIPTION: Defines the syntax for the `text-align` CSS property in Textual, specifying that it accepts a value of type `<text-align>`.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_align.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
text-align: <a href="../../css_types/text_align">&lt;text-align&gt;</a>;
```

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

TITLE: Set Text Alignment in CSS
DESCRIPTION: Illustrates how to apply the `text-align` property in a Textual CSS (TCSS) stylesheet to align text to the right.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_align.md#_snippet_1

LANGUAGE: CSS
CODE:
```
/* Set text in the widget to be right aligned */
text-align: right;
```

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

TITLE: Start Textual Console with Verbose Logging
DESCRIPTION: Launches the Textual debug console with increased verbosity, displaying additional log messages that are typically excluded to provide more detailed debugging information.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/devtools.md#_snippet_13

LANGUAGE: bash
CODE:
```
textual console -v
```

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

TITLE: CSS Color Style Syntax Definition
DESCRIPTION: Defines the syntax for the `color` CSS property in Textual. It accepts a color value (e.g., named color, RGB) or the keyword 'auto'. An optional percentage can be appended to specify opacity. 'auto' automatically selects a contrasting text color.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/color.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
color: (<color> | auto) [<percentage>];
```

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

TITLE: Setting Screen Background Color to Lime
DESCRIPTION: A simple example demonstrating how to set the background color of the Textual screen to 'lime' using a predefined color name. This is a direct assignment to the screen's styles attribute.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/styles.md#_snippet_2

LANGUAGE: Python
CODE:
```
self.screen.styles.background = "lime"
```

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

TITLE: Implement Textual App Event Handlers (on_mount, on_key)
DESCRIPTION: This snippet showcases how to define event handlers within a Textual application to respond to lifecycle events and user input. It includes `on_mount` for initial setup tasks, such as setting the screen background, and `on_key` for processing keyboard presses, demonstrating how to access event-specific data like the pressed key.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/app.md#_snippet_3

LANGUAGE: python
CODE:
```
from textual.app import App
from textual.events import Key

class EventApp(App):
    """An app with event handlers."""

    def on_mount(self) -> None:
        self.screen.styles.background = "darkblue"

    def on_key(self, event: Key) -> None:
        if event.key.isdigit():
            self.screen.styles.background = f"rgb({int(event.key) * 25}, 0, 0)"
    
if __name__ == "__main__":
    app = EventApp()
    app.run()
```

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

TITLE: Pop Screen from Textual App Stack
DESCRIPTION: Documents the `pop_screen` method of `textual.app.App` for removing the top-most screen and the associated 'app.pop_screen' action. Highlights the `ScreenStackError` if attempting to remove the last screen, as the stack must always have at least one screen. The screen is removed and deleted unless it's installed or another copy exists.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/screens.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
textual.app.App.pop_screen()
  Removes the top-most screen from the stack.
  The new top screen becomes active.
  Raises: ScreenStackError if attempting to remove the last screen.
  Note: The screen is removed and deleted unless installed or another copy exists on the stack.
```

LANGUAGE: Textual Action
CODE:
```
"app.pop_screen"
```

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

TITLE: CSS Margin Property Examples
DESCRIPTION: Illustrates different ways to apply `margin` and individual `margin-` properties in CSS, showing single-value, two-value, and four-value notations, as well as specific edge margins for top, right, bottom, and left.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/margin.md#_snippet_1

LANGUAGE: css
CODE:
```
/* Set margin of 1 around all edges */
margin: 1;
/* Set margin of 2 on the top and bottom edges, and 4 on the left and right */
margin: 2 4;
/* Set margin of 1 on the top, 2 on the right,
                 3 on the bottom, and 4 on the left */
margin: 1 2 3 4;

margin-top: 1;
margin-right: 2;
margin-bottom: 3;
margin-left: 4;
```

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

TITLE: Textual Recompose: Basic Widget Re-rendering Example
DESCRIPTION: Demonstrates the `recompose=True` attribute on a reactive, causing Textual to remove and re-mount child widgets when the reactive attribute changes. This example shows how a `compose()` method is re-called to update content.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/reactivity.md#_snippet_6

LANGUAGE: python
CODE:
```
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label
from textual.reactive import reactive
from textual.containers import Container

class Name(Container):
    who = reactive("World", recompose=True)

    def compose(self) -> ComposeResult:
        yield Label(f"Hello, {self.who}!")

class RecomposeApp(App):
    BINDINGS = [("p", "prompt", "Prompt Name")]

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

    def action_prompt(self) -> None:
        self.query_one(Name).who = "Paul"

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

LANGUAGE: css
CODE:
```
Name {
    border: solid green;
    padding: 1;
    width: auto;
}
Label {
    text-align: center;
}
```

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

TITLE: Setting Default Background for Buttons in Textual CSS
DESCRIPTION: This basic CSS rule sets the default background color for all `Button` widgets to green, providing a consistent visual style across the application.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/CSS.md#_snippet_23

LANGUAGE: css
CODE:
```
Button {
  background: green;
}
```

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

TITLE: Python Checkbox Widget Example Code
DESCRIPTION: Python source code for the Checkbox widget example, included from an external file.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/checkbox.md#_snippet_1

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/widgets/checkbox.py"
```

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

TITLE: Define a Basic Custom Textual Widget
DESCRIPTION: This snippet demonstrates the fundamental way to create a custom Textual widget by importing and extending the base `Widget` class. It shows how to implement the `render()` method, which Textual calls to display content within the widget's area, supporting content markup for styling.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_0

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/hello01.py"
```

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

TITLE: Define a Minimal Textual App Class
DESCRIPTION: This snippet illustrates the most basic structure for a Textual application. It defines a class that inherits from `textual.app.App`, serving as the essential foundation for any Textual UI.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/app.md#_snippet_0

LANGUAGE: python
CODE:
```
from textual.app import App

class MyApp(App):
    """My first Textual app."""
```

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

TITLE: Text-wrap CSS Property Usage Examples
DESCRIPTION: Provides examples of how to apply the `text-wrap` CSS property within a stylesheet to control text wrapping behavior, demonstrating both `wrap` and `nowrap` values.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_wrap.md#_snippet_1

LANGUAGE: css
CODE:
```
text-wrap: wrap;
text-wrap: nowrap;
```

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

TITLE: Textual Widget Text-wrap Style Assignment in Python
DESCRIPTION: Demonstrates how to programmatically set the `text-wrap` style for a Textual widget using Python, allowing developers to dynamically enable or disable text wrapping.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_wrap.md#_snippet_2

LANGUAGE: py
CODE:
```
widget.styles.text_wrap = "wrap"
widget.styles.text_wrap = "nowrap"
```

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

TITLE: Textual CSS Outline Property Syntax Definition
DESCRIPTION: Defines the syntax for the `outline` CSS property and its individual side-specific properties (`outline-top`, `outline-right`, `outline-bottom`, `outline-left`). It specifies accepted values for border style and color, noting that this property draws a box over the content area.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/outline.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
outline: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];

outline-top: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];
outline-right: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];
outline-bottom: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];
outline-left: [<a href="../../css_types/border">&lt;border&gt;</a>] [<a href="../../css_types/color">&lt;color&gt;</a>];
```

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

TITLE: Textual TextArea Class Full API Reference
DESCRIPTION: Indicates the inclusion point for the comprehensive API documentation of the `textual.widgets._text_area.TextArea` class, covering its methods, properties, and events in detail.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/text_area.md#_snippet_35

LANGUAGE: APIDOC
CODE:
```
Full API Documentation for Class: textual.widgets._text_area.TextArea
```

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

TITLE: Textual Python Tint Style Usage Examples
DESCRIPTION: Demonstrates how to programmatically set the `tint` style on a Textual widget using Python. This includes setting a red tint by manipulating a `Color` object's alpha and applying a green tint using a direct RGBA string.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/tint.md#_snippet_2

LANGUAGE: python
CODE:
```
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)"
```

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

TITLE: Compose Textual Widgets Using Python Context Managers
DESCRIPTION: Illustrates an alternative, more idiomatic way to compose Textual widgets using Python's `with` statement. This method simplifies the nesting of containers and the addition of child widgets, making the code cleaner and easier to read compared to positional arguments.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/layout.md#_snippet_2

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/layout/utility_containers_using_with.py"
```

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/layout/utility_containers.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/layout/utility_containers.tcss"
```

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

TITLE: Common CSS Color Property Usages
DESCRIPTION: Demonstrates various ways to set the `color` property in CSS, including named colors, percentage opacity, RGB values, and the 'auto' keyword for automatic contrast selection.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/color.md#_snippet_1

LANGUAGE: css
CODE:
```
/* Blue text */
color: blue;

/* 20% red text */
color: red 20%;

/* RGB color */
color: rgb(100, 120, 200);

/* Automatically choose color with suitable contrast for readability */
color: auto;
```

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

TITLE: Textual Python Examples for Setting link-style-hover
DESCRIPTION: Shows how to programmatically set the `link-style-hover` property for a Textual widget's styles in Python, applying different text styles on link hover.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/links/link_style_hover.md#_snippet_2

LANGUAGE: python
CODE:
```
widget.styles.link_style_hover = "bold"
widget.styles.link_style_hover = "bold italic reverse"
```

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

TITLE: Textual Python Background Style Examples
DESCRIPTION: Demonstrates how to apply background styles to Textual widgets using Python, either with CSS-like string assignments or by instantiating `Color` objects directly.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/background.md#_snippet_2

LANGUAGE: python
CODE:
```
# Set blue background
widget.styles.background = "blue"
# Set through HSL model
widget.styles.background = "hsl(351,32%,89%)"

from textual.color import Color
# Set with a color object by parsing a string
widget.styles.background = Color.parse("pink")
widget.styles.background = Color.parse("#FF00FF")
# Set with a color object instantiated directly
widget.styles.background = Color(120, 60, 100)
```

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

TITLE: Display Textual CLI Help
DESCRIPTION: Shows the main help message for the Textual command-line application, listing all available subcommands and global options.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/devtools.md#_snippet_0

LANGUAGE: bash
CODE:
```
textual --help
```

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

TITLE: Run Textual App in Development Mode
DESCRIPTION: Executes a Textual application with the `--dev` switch, enabling development features such as live CSS editing, where changes are reflected instantly.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/devtools.md#_snippet_10

LANGUAGE: bash
CODE:
```
textual run --dev my_app.py
```

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

TITLE: Textual CSS Align Property Syntax Definition
DESCRIPTION: Defines the syntax for the `align`, `align-horizontal`, and `align-vertical` CSS properties used in Textual, specifying the allowed horizontal and vertical values for positioning child elements.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/align.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
align: <horizontal> <vertical>;

align-horizontal: <horizontal>;
align-vertical: <vertical>;
```

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

TITLE: Configure Border Titles and Subtitles for Textual Widgets
DESCRIPTION: Illustrates how to set border titles and subtitles for Textual widgets. This feature allows displaying text within the top and bottom borders of a widget. Titles can be set via instance attributes (`border_title`, `border_subtitle`) or as default class variables (`BORDER_TITLE`, `BORDER_SUBTITLE`). Note that borders must be enabled for titles to display.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/widgets.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
textual.widgets.Widget:
  Attributes:
    border_title: str
      Description: Text displayed within the top border of the widget.
    border_subtitle: str
      Description: Text displayed within the bottom border of the widget.
  Class Variables:
    BORDER_TITLE: str
      Description: Default value for the border_title attribute.
    BORDER_SUBTITLE: str
      Description: Default value for the border_subtitle attribute.
```

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/guide/widgets/hello06.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/guide/widgets/hello06.tcss"
```

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

TITLE: Textual Pilot Class for UI Interaction
DESCRIPTION: Details the `Pilot` object, which is returned by `App.run_test()`. This class provides methods to simulate user interactions like key presses and button clicks within a Textual application during automated tests.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/testing.md#_snippet_1

LANGUAGE: APIDOC
CODE:
```
textual.pilot.Pilot:
  Type: Class
  Description: An object used to interact with a Textual app during testing, simulating keyboard and mouse operations.
  Methods:
    press(key: str):
      Description: Simulates pressing a key.
      Parameters:
        key: str - The key to simulate pressing.
    click(widget_id: str):
      Description: Simulates clicking on a widget.
      Parameters:
        widget_id: str - The ID of the widget to click.
```

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

TITLE: Customizing Sparkline Colors in Textual CSS
DESCRIPTION: Shows how to apply component classes within Textual's CSS to modify the visual appearance and colors of the Sparkline widget, allowing for custom styling.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/sparkline.md#_snippet_2

LANGUAGE: python
CODE:
```
--8<-- "docs/examples/widgets/sparkline_colors.py"
```

LANGUAGE: css
CODE:
```
--8<-- "docs/examples/widgets/sparkline_colors.tcss"
```

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

TITLE: Get Last Matching Widget with Textual DOMQuery
DESCRIPTION: This snippet demonstrates how to use the `last()` method on a Textual `DOMQuery` object to retrieve the last widget that matches a given selector. It queries for all "Button" widgets and then selects the last one found. If no matches exist, a `NoMatches` exception is raised.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/queries.md#_snippet_11

LANGUAGE: python
CODE:
```
last_button = self.query("Button").last()
```

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

TITLE: Set Scrollbar Background Hover Color in CSS
DESCRIPTION: Demonstrates how to apply the `scrollbar-background-hover` property directly within a CSS stylesheet to set the scrollbar's background color to purple when hovered.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/scrollbar_colors/scrollbar_background_hover.md#_snippet_1

LANGUAGE: css
CODE:
```
scrollbar-background-hover: purple;
```

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

TITLE: CSS Border Style Syntax Reference
DESCRIPTION: Formal syntax definition for the `border` and individual edge `border-` properties in CSS, specifying the expected types for border style, color, and an optional percentage for blending with the background.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/border.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
border: [<border>] [<color>] [<percentage>];

border-top: [<border>] [<color>] [<percentage>];
border-right: [<border>] [<color>] [<percentage>];
border-bottom: [<border>] [<color>] [<percentage>];
border-left: [<border>] [<color>] [<percentage>];
```

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

TITLE: Collapsible Widget Reactive Attributes API
DESCRIPTION: API documentation for the reactive attributes of the Collapsible widget, detailing their names, types, default values, and descriptions.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/collapsible.md#_snippet_4

LANGUAGE: APIDOC
CODE:
```
Reactive Attributes:
  collapsed:
    Type: bool
    Default: True
    Description: Controls the collapsed/expanded state of the widget.
  title:
    Type: str
    Default: "Toggle"
    Description: Title of the collapsed/expanded contents.
```

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

TITLE: Launch Textual Markup Playground
DESCRIPTION: This command launches the interactive Textual markup playground, allowing users to experiment with content markup and see live results directly in the terminal.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/content.md#_snippet_0

LANGUAGE: Shell
CODE:
```
python -m textual.markup
```

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

TITLE: textual.widgets.option_list Module API Reference
DESCRIPTION: API reference for the `option_list` module, containing the OptionList widget.
SOURCE: https://github.com/textualize/textual/blob/main/docs/widgets/option_list.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
textual.widgets.option_list
```

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

TITLE: Retrieve Single Widget by ID and Type with query_one
DESCRIPTION: Shows how to use `self.query_one()` with an ID selector and an expected type. This ensures type safety, allowing type-checkers like MyPy to infer the exact return type, and raises a `WrongType` exception if the matched widget does not conform to the specified type.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/queries.md#_snippet_1

LANGUAGE: python
CODE:
```
send_button = self.query_one("#send", Button)
```

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

TITLE: Textual CLI Command for Interactive Border Exploration
DESCRIPTION: A command-line interface subcommand provided by Textual to interactively explore and visualize various border types available for widgets.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/border.md#_snippet_1

LANGUAGE: Shell
CODE:
```
textual borders
```

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

TITLE: CSS Syntax for border-title-align Property
DESCRIPTION: Defines the standard CSS syntax for the `border-title-align` property. This property accepts a `<horizontal>` value to specify the horizontal alignment of a border's title.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/border_title_align.md#_snippet_0

LANGUAGE: css
CODE:
```
border-title-align: <horizontal>;
```

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

TITLE: Apply Border Title Style in CSS and Python
DESCRIPTION: Examples demonstrating how to set the `border-title-style` to `bold underline` using both CSS and Python for Textual widgets.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/border_title_style.md#_snippet_1

LANGUAGE: CSS
CODE:
```
border-title-style: bold underline;
```

LANGUAGE: Python
CODE:
```
widget.styles.border_title_style = "bold underline"
```

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

TITLE: CSS Syntax for border-title-style Property
DESCRIPTION: Defines the valid syntax for the `border-title-style` CSS property, indicating it accepts a `<text-style>` value.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/border_title_style.md#_snippet_0

LANGUAGE: CSS
CODE:
```
border-title-style: <text-style>;
```

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

TITLE: Textual Message Handler with Event Object Parameter (`on` Decorator)
DESCRIPTION: This example illustrates a Textual message handler defined using the `@on` decorator, which also takes the event object (`message`) as a parameter. This enables the handler to utilize event-specific data, such as `message.color`, for animating background colors, demonstrating the decorator's flexibility.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/events.md#_snippet_5

LANGUAGE: python
CODE:
```
    @on(ColorButton.Selected)
    def animate_background_color(self, message: ColorButton.Selected) -> None:
        self.screen.styles.animate("background", message.color, duration=0.5)
```

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

TITLE: Textual Clock Example: Simplified with Recompose
DESCRIPTION: Shows a simplified clock application using `recompose=True` on the `time` reactive attribute. This eliminates the need for a separate `watch_time` method, as the `Digits` widget is entirely replaced with a new instance containing the updated time.
SOURCE: https://github.com/textualize/textual/blob/main/docs/guide/reactivity.md#_snippet_8

LANGUAGE: python
CODE:
```
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label
from textual.reactive import reactive
from textual.containers import Container
import datetime

class Digits(Container):
    time = reactive(datetime.datetime.now(), recompose=True)

    def compose(self) -> ComposeResult:
        yield Label(self.time.strftime("%H:%M:%S"))

class RecomposeClockApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Digits()
        yield Footer()

    def on_mount(self) -> None:
        self.set_interval(1, self.update_time)

    def update_time(self) -> None:
        self.query_one(Digits).time = datetime.datetime.now()

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

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

TITLE: Set Text Alignment in Textual Python
DESCRIPTION: Shows how to programmatically set the `text-align` style of a Textual widget instance to `right` using Python.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/text_align.md#_snippet_2

LANGUAGE: Python
CODE:
```
# Set text in the widget to be right aligned
widget.styles.text_align = "right"
```

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

TITLE: Textual CSS Align Property Usage Examples
DESCRIPTION: Provides practical examples of how to use the `align` CSS property and its individual `align-horizontal` and `align-vertical` components to position child widgets within a container in Textual applications.
SOURCE: https://github.com/textualize/textual/blob/main/docs/styles/align.md#_snippet_1

LANGUAGE: css
CODE:
```
/* 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;
```