61 lines
1.8 KiB
Markdown
61 lines
1.8 KiB
Markdown
|
# 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
|