# Textual API Reference

This directory contains a comprehensive reference for the Textual library API, focusing on the components used in StreamLens.

## Overview

Textual is a TUI (Text User Interface) framework for Python. This reference covers the key APIs we use.

## Quick Links

- [DataTable Widget Reference](./datatable.md) - Complete DataTable API
- [Events Reference](./events.md) - Event handling and messages
- [Common Widgets](./widgets.md) - Other widgets used in StreamLens
- [Styling Guide](./styling.md) - CSS and styling reference

## Core Concepts

### Messages and Events

Textual uses a message-passing system for communication between widgets:

1. **Events** - User interactions (keyboard, mouse)
2. **Messages** - Widget-to-widget communication
3. **Handlers** - Methods that respond to events/messages

### Event Handler Naming

Event handlers follow the pattern: `on_<widget_class>_<event_name>`

Example:
```python
def on_data_table_row_selected(self, event: DataTable.RowSelected):
    # Handle row selection
```

### Common Pitfalls

1. **RowKey Type**: DataTable row keys are not strings by default
2. **Event Names**: Check exact event class names (e.g., `RowHighlighted` not `CursorMoved`)
3. **Method Availability**: Not all expected methods exist (e.g., no `set_row_style()`)

## API Validation

Always validate API usage before implementation:

```python
# Check available events
from textual.widgets import DataTable
print([attr for attr in dir(DataTable) if 'Selected' in attr or 'Highlighted' in attr])

# Check specific method
print(hasattr(DataTable, 'method_name'))
```

## Directory Structure

- `datatable.md` - Complete DataTable API reference
- `events.md` - Events and message handling
- `widgets.md` - Common widget APIs
- `styling.md` - CSS and theming
- `examples/` - Working code examples