alihan/textual
1
0
Fork 0
mirror of https://github.com/Textualize/textual.git synced 2025-10-17 02:38:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'css' of github.com:willmcgugan/textual into snapshot

Browse Source
This commit is contained in:
Darren Burns
2022-09-20 14:46:37 +01:00
parent 7428a164df f70232ca5c
commit 0cd5c0a298
148 changed files with 3626 additions and 2197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/README.md → docs.md
View File

2
docs/examples/app/event01.py
View File

@@ -25,6 +25,6 @@ class EventApp(App):
self.screen.styles.background = self.COLORS[int(event.key)]
app = EventApp()
if __name__ == "__main__":
app = EventApp()
app.run()

2
docs/examples/app/question01.py
View File

@@ -12,7 +12,7 @@ class QuestionApp(App[str]):
self.exit(event.button.id)
app = QuestionApp()
if __name__ == "__main__":
app = QuestionApp()
reply = app.run()
print(reply)

4
docs/examples/app/question02.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static, Button
class QuestionApp(App[str]):
CSS_PATH = "question02.css"
def compose(self) -> ComposeResult:
yield Static("Do you love Textual?", id="question")
yield Button("Yes", id="yes", variant="primary")
@@ -12,7 +14,7 @@ class QuestionApp(App[str]):
self.exit(event.button.id)
app = QuestionApp(css_path="question02.css")
if __name__ == "__main__":
app = QuestionApp()
reply = app.run()
print(reply)

2
docs/examples/app/question03.py
View File

@@ -32,7 +32,7 @@ class QuestionApp(App[str]):
self.exit(event.button.id)
app = QuestionApp()
if __name__ == "__main__":
app = QuestionApp()
reply = app.run()
print(reply)

2
docs/examples/app/return.py
View File

@@ -9,6 +9,6 @@ class ButtonsApp(App):
yield Button("Chani")
app = ButtonsApp()
if __name__ == "__main__":
app = ButtonsApp()
app.run()

2
docs/examples/app/simple02.py
View File

@@ -5,6 +5,6 @@ class MyApp(App):
pass
app = MyApp()
if __name__ == "__main__":
app = MyApp()
app.run()

2
docs/examples/app/widgets01.py
View File

@@ -10,6 +10,6 @@ class WelcomeApp(App):
self.exit()
app = WelcomeApp()
if __name__ == "__main__":
app = WelcomeApp()
app.run()

2
docs/examples/app/widgets02.py
View File

@@ -10,6 +10,6 @@ class WelcomeApp(App):
self.exit()
app = WelcomeApp()
if __name__ == "__main__":
app = WelcomeApp()
app.run()

253
docs/examples/basic.css
View File

@@ -1,253 +0,0 @@
/* CSS file for basic.py */
* {
transition: color 300ms linear, background 300ms linear;
}
*:hover {
/* tint: 30% red;
/* outline: heavy red; */
}
App > Screen {
background: $surface;
color: $text;
layers: base sidebar;
color: $text;
background: $background;
layout: vertical;
overflow: hidden;
}
#tree-container {
overflow-y: auto;
height: 20;
margin: 1 3;
background: $panel;
padding: 1 2;
}
DirectoryTree {
padding: 0 1;
height: auto;
}
DataTable {
/*border:heavy red;*/
/* tint: 10% green; */
/* text-opacity: 50%; */
padding: 1;
margin: 1 2;
height: 24;
}
#sidebar {
color: $text;
background: $panel;
dock: left;
width: 30;
margin-bottom: 1;
offset-x: -100%;
transition: offset 500ms in_out_cubic;
layer: sidebar;
}
#sidebar.-active {
offset-x: 0;
}
#sidebar .title {
height: 1;
background: $primary-background-darken-1;
color: $text-muted;
border-right: wide $background;
content-align: center middle;
}
#sidebar .user {
height: 8;
background: $panel-darken-1;
color: $text-muted;
border-right: wide $background;
content-align: center middle;
}
#sidebar .content {
background: $panel-darken-2;
color: $text;
border-right: wide $background;
content-align: center middle;
}
Tweet {
height:12;
width: 100%;
margin: 0 2;
background: $panel;
color: $text;
layout: vertical;
/* border: outer $primary; */
padding: 1;
border: wide $panel;
overflow: auto;
/* scrollbar-gutter: stable; */
align-horizontal: center;
box-sizing: border-box;
}
.scrollable {
overflow-x: auto;
overflow-y: scroll;
margin: 1 2;
height: 24;
align-horizontal: center;
layout: vertical;
}
.code {
height: auto;
}
TweetHeader {
height:1;
background: $accent;
color: $text
}
TweetBody {
width: 100%;
background: $panel;
color: $text;
height: auto;
padding: 0 1 0 0;
}
Tweet.scroll-horizontal TweetBody {
width: 350;
}
.button {
background: $accent;
color: $text;
width:20;
height: 3;
/* border-top: hidden $accent-darken-3; */
border: tall $accent-darken-2;
/* border-left: tall $accent-darken-1; */
/* padding: 1 0 0 0 ; */
transition: background 400ms in_out_cubic, color 400ms in_out_cubic;
}
.button:hover {
background: $accent-lighten-1;
color: $text-disabled;
width: 20;
height: 3;
border: tall $accent-darken-1;
/* border-left: tall $accent-darken-3; */
}
#footer {
color: $text;
background: $accent;
height: 1;
content-align: center middle;
dock:bottom;
}
#sidebar .content {
layout: vertical
}
OptionItem {
height: 3;
background: $panel;
border-right: wide $background;
border-left: blank;
content-align: center middle;
}
OptionItem:hover {
height: 3;
color: $text;
background: $primary-darken-1;
/* border-top: hkey $accent2-darken-3;
border-bottom: hkey $accent2-darken-3; */
text-style: bold;
border-left: outer $secondary-darken-2;
}
Error {
width: 100%;
height:3;
background: $error;
color: $text;
border-top: tall $error-darken-2;
border-bottom: tall $error-darken-2;
padding: 0;
text-style: bold;
align-horizontal: center;
}
Warning {
width: 100%;
height:3;
background: $warning;
color: $text-muted;
border-top: tall $warning-darken-2;
border-bottom: tall $warning-darken-2;
text-style: bold;
align-horizontal: center;
}
Success {
width: 100%;
height:auto;
box-sizing: border-box;
background: $success;
color: $text-muted;
border-top: hkey $success-darken-2;
border-bottom: hkey $success-darken-2;
text-style: bold ;
align-horizontal: center;
}
.horizontal {
layout: horizontal
}

234
docs/examples/demo.py
View File

@@ -1,234 +0,0 @@
from rich.console import RenderableType
from rich.syntax import Syntax
from rich.text import Text
from textual.app import App, ComposeResult
from textual.reactive import Reactive
from textual.widget import Widget
from textual.widgets import Static, DataTable, DirectoryTree, Header, Footer
from textual.layout import Container
CODE = '''
from __future__ import annotations
from typing import Iterable, TypeVar
T = TypeVar("T")
def loop_first(values: Iterable[T]) -> Iterable[tuple[bool, T]]:
"""Iterate and generate a tuple with a flag for first value."""
iter_values = iter(values)
try:
value = next(iter_values)
except StopIteration:
return
yield True, value
for value in iter_values:
yield False, value
def loop_last(values: Iterable[T]) -> Iterable[tuple[bool, T]]:
"""Iterate and generate a tuple with a flag for last value."""
iter_values = iter(values)
try:
previous_value = next(iter_values)
except StopIteration:
return
for value in iter_values:
yield False, previous_value
previous_value = value
yield True, previous_value
def loop_first_last(values: Iterable[T]) -> Iterable[tuple[bool, bool, T]]:
"""Iterate and generate a tuple with a flag for first and last value."""
iter_values = iter(values)
try:
previous_value = next(iter_values)
except StopIteration:
return
first = True
for value in iter_values:
yield first, False, previous_value
first = False
previous_value = value
yield first, True, previous_value
'''
lorem_short = """Lorem ipsum dolor sit amet, consectetur adipiscing elit. In velit liber a a a, volutpat nec hendrerit at, faucibus in odio. Aliquam hendrerit nibh sed quam volutpat maximus. Nullam suscipit convallis lorem quis sodales. In tristique lobortis ante et dictum. Ut at finibus ipsum."""
lorem = (
lorem_short
+ """ In urna dolor, placerat et mi facilisis, congue sollicitudin massa. Phasellus felis turpis, cursus eu lectus et, porttitor malesuada augue. Sed feugiat volutpat velit, sollicitudin fringilla velit bibendum faucibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In velit libero, volutpat nec hendrerit at, faucibus in odio. Aliquam hendrerit nibh sed quam volutpat maximus. Nullam suscipit convallis lorem quis sodales. In tristique lobortis ante et dictum. Ut at finibus ipsum. In urna dolor, placerat et mi facilisis, congue sollicitudin massa. Phasellus felis turpis, cursus eu lectus et, porttitor malesuada augue. Sed feugiat volutpat velit, sollicitudin fringilla velit bibendum faucibus. """
)
lorem_short_text = Text.from_markup(lorem_short)
lorem_long_text = Text.from_markup(lorem * 2)
class TweetHeader(Widget):
def render(self) -> RenderableType:
return Text("Lorem Impsum", justify="center")
class TweetBody(Widget):
short_lorem = Reactive(False)
def render(self) -> Text:
return lorem_short_text if self.short_lorem else lorem_long_text
class Tweet(Widget):
pass
class OptionItem(Widget):
def render(self) -> Text:
return Text("Option")
class Error(Widget):
def render(self) -> Text:
return Text("This is an error message", justify="center")
class Warning(Widget):
def render(self) -> Text:
return Text("This is a warning message", justify="center")
class Success(Widget):
def render(self) -> Text:
return Text("This is a success message", justify="center")
class BasicApp(App, css_path="basic.css"):
"""A basic app demonstrating CSS"""
def on_load(self):
"""Bind keys here."""
self.bind("s", "toggle_class('#sidebar', '-active')", description="Sidebar")
self.bind("d", "toggle_dark", description="Dark mode")
self.bind("q", "quit", description="Quit")
self.bind("f", "query_test", description="Query test")
def compose(self):
yield Header()
table = DataTable()
self.scroll_to_target = Tweet(TweetBody())
yield Container(
Tweet(TweetBody()),
Widget(
Static(
Syntax(CODE, "python", line_numbers=True, indent_guides=True),
classes="code",
),
classes="scrollable",
),
table,
Error(),
Tweet(TweetBody(), classes="scrollbar-size-custom"),
Warning(),
Tweet(TweetBody(), classes="scroll-horizontal"),
Success(),
Tweet(TweetBody(), classes="scroll-horizontal"),
Tweet(TweetBody(), classes="scroll-horizontal"),
Tweet(TweetBody(), classes="scroll-horizontal"),
Tweet(TweetBody(), classes="scroll-horizontal"),
Tweet(TweetBody(), classes="scroll-horizontal"),
)
yield Widget(
Widget(classes="title"),
Widget(classes="user"),
OptionItem(),
OptionItem(),
OptionItem(),
Widget(classes="content"),
id="sidebar",
)
yield Footer()
table.add_column("Foo", width=20)
table.add_column("Bar", width=20)
table.add_column("Baz", width=20)
table.add_column("Foo", width=20)
table.add_column("Bar", width=20)
table.add_column("Baz", width=20)
table.zebra_stripes = True
for n in range(100):
table.add_row(*[f"Cell ([b]{n}[/b], {col})" for col in range(6)])
def on_mount(self):
self.sub_title = "Widget demo"
async def on_key(self, event) -> None:
await self.dispatch_key(event)
def action_toggle_dark(self):
self.dark = not self.dark
def action_query_test(self):
query = self.query("Tweet")
self.log(query)
self.log(query.nodes)
self.log(query)
self.log(query.nodes)
query.set_styles("outline: outer red;")
query = query.exclude(".scroll-horizontal")
self.log(query)
self.log(query.nodes)
# query = query.filter(".rubbish")
# self.log(query)
# self.log(query.first())
async def key_q(self):
await self.shutdown()
def key_x(self):
self.panic(self.tree)
def key_escape(self):
self.app.bell()
def key_t(self):
# Pressing "t" toggles the content of the TweetBody widget, from a long "Lorem ipsum..." to a shorter one.
tweet_body = self.query("TweetBody").first()
tweet_body.short_lorem = not tweet_body.short_lorem
def key_v(self):
self.get_child(id="content").scroll_to_widget(self.scroll_to_target)
def key_space(self):
self.bell()
app = BasicApp()
if __name__ == "__main__":
app.run()
# from textual.geometry import Region
# from textual.color import Color
# print(Region.intersection.cache_info())
# print(Region.overlaps.cache_info())
# print(Region.union.cache_info())
# print(Region.split_vertical.cache_info())
# print(Region.__contains__.cache_info())
# from textual.css.scalar import Scalar
# print(Scalar.resolve_dimension.cache_info())
# from rich.style import Style
# from rich.cells import cached_cell_len
# print(Style._add.cache_info())
# print(cached_cell_len.cache_info())

48
docs/examples/events/custom01.py Normal file
View File

@@ -0,0 +1,48 @@
from textual.app import App, ComposeResult
from textual.color import Color
from textual.message import Message, MessageTarget
from textual.widgets import Static
class ColorButton(Static):
"""A color button."""
class Selected(Message):
"""Color selected message."""
def __init__(self, sender: MessageTarget, color: Color) -> None:
self.color = color
super().__init__(sender)
def __init__(self, color: Color) -> None:
self.color = color
super().__init__()
def on_mount(self) -> None:
self.styles.margin = (1, 2)
self.styles.content_align = ("center", "middle")
self.styles.background = Color.parse("#ffffff33")
self.styles.border = ("tall", self.color)
async def on_click(self) -> None:
# The emit method sends an event to a widget's parent
await self.emit(self.Selected(self, self.color))
def render(self) -> str:
return str(self.color)
class ColorApp(App):
def compose(self) -> ComposeResult:
yield ColorButton(Color.parse("#008080"))
yield ColorButton(Color.parse("#808000"))
yield ColorButton(Color.parse("#E9967A"))
yield ColorButton(Color.parse("#121212"))
def on_color_button_selected(self, message: ColorButton.Selected) -> None:
self.screen.styles.animate("background", message.color, duration=0.5)
if __name__ == "__main__":
app = ColorApp()
app.run()

29
docs/examples/events/dictionary.css Normal file
View File

@@ -0,0 +1,29 @@
Screen {
background: $panel;
}
TextInput {
dock: top;
border: tall $background;
width: 100%;
height: 1;
padding: 0 1;
margin: 1 1 0 1;
background: $boost;
}
TextInput:focus {
border: tall $accent;
}
#results {
width: auto;
min-height: 100%;
}
#results-container {
background: $background 50%;
overflow: auto;
margin: 1 2;
height: 100%;
}

45
docs/examples/events/dictionary.py Normal file
View File

@@ -0,0 +1,45 @@
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.layout import Vertical
from textual.widgets import Static, TextInput
class DictionaryApp(App):
"""Searches ab dictionary API as-you-type."""
CSS_PATH = "dictionary.css"
def compose(self) -> ComposeResult:
yield TextInput(placeholder="Search for a word")
yield Vertical(Static(id="results", fluid=False), id="results-container")
async def on_text_input_changed(self, message: TextInput.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(TextInput).value:
self.query_one("#results", Static).update(JSON(results))
if __name__ == "__main__":
app = DictionaryApp()
app.run()

2
docs/examples/guide/dom1.py
View File

@@ -5,6 +5,6 @@ class ExampleApp(App):
pass
app = ExampleApp()
if __name__ == "__main__":
app = ExampleApp()
app.run()

2
docs/examples/guide/dom2.py
View File

@@ -8,6 +8,6 @@ class ExampleApp(App):
yield Footer()
app = ExampleApp()
if __name__ == "__main__":
app = ExampleApp()
app.run()

2
docs/examples/guide/dom3.py
View File

@@ -20,6 +20,6 @@ class ExampleApp(App):
)
app = ExampleApp()
if __name__ == "__main__":
app = ExampleApp()
app.run()

2
docs/examples/guide/dom4.css
View File

@@ -2,7 +2,7 @@
/* The top level dialog (a Container) */
#dialog {
margin: 4 8;
background: $primary;
background: $panel;
color: $text;
border: tall $background;
padding: 1 2;

6
docs/examples/guide/dom4.py
View File

@@ -6,6 +6,8 @@ QUESTION = "Do you want to learn about Textual CSS?"
class ExampleApp(App):
CSS_PATH = "dom4.css"
def compose(self) -> ComposeResult:
yield Header()
yield Footer()
@@ -20,4 +22,6 @@ class ExampleApp(App):
)
app = ExampleApp(css_path="dom4.css")
if __name__ == "__main__":
app = ExampleApp()
app.run()

4
docs/examples/guide/layout/center_layout.py
View File

@@ -3,12 +3,14 @@ from textual.widgets import Static
class CenterLayoutExample(App):
CSS_PATH = "center_layout.css"
def compose(self) -> ComposeResult:
yield Static("One", id="bottom")
yield Static("Two", id="middle")
yield Static("Three", id="top")
app = CenterLayoutExample(css_path="center_layout.css")
if __name__ == "__main__":
app = CenterLayoutExample()
app.run()

4
docs/examples/guide/layout/combining_layouts.py
View File

@@ -4,6 +4,8 @@ from textual.widgets import Static, Header
class CombiningLayoutsExample(App):
CSS_PATH = "combining_layouts.css"
def compose(self) -> ComposeResult:
yield Header()
yield layout.Container(
@@ -38,6 +40,6 @@ class CombiningLayoutsExample(App):
print(self.stylesheet.variables["boost-lighten-2"])
app = CombiningLayoutsExample(css_path="combining_layouts.css")
if __name__ == "__main__":
app = CombiningLayoutsExample()
app.run()

4
docs/examples/guide/layout/dock_layout1_sidebar.py
View File

@@ -10,11 +10,13 @@ Docked widgets will not scroll out of view, making them ideal for sticky headers
class DockLayoutExample(App):
CSS_PATH = "dock_layout1_sidebar.css"
def compose(self) -> ComposeResult:
yield Static("Sidebar", id="sidebar")
yield Static(TEXT * 10, id="body")
app = DockLayoutExample(css_path="dock_layout1_sidebar.css")
if __name__ == "__main__":
app = DockLayoutExample()
app.run()

4
docs/examples/guide/layout/dock_layout2_sidebar.py
View File

@@ -10,12 +10,14 @@ Docked widgets will not scroll out of view, making them ideal for sticky headers
class DockLayoutExample(App):
CSS_PATH = "dock_layout2_sidebar.css"
def compose(self) -> ComposeResult:
yield Static("Sidebar2", id="another-sidebar")
yield Static("Sidebar1", id="sidebar")
yield Static(TEXT * 10, id="body")
app = DockLayoutExample(css_path="dock_layout2_sidebar.css")
app = DockLayoutExample()
if __name__ == "__main__":
app.run()

4
docs/examples/guide/layout/dock_layout3_sidebar_header.py
View File

@@ -10,12 +10,14 @@ Docked widgets will not scroll out of view, making them ideal for sticky headers
class DockLayoutExample(App):
CSS_PATH = "dock_layout3_sidebar_header.css"
def compose(self) -> ComposeResult:
yield Header(id="header")
yield Static("Sidebar1", id="sidebar")
yield Static(TEXT * 10, id="body")
app = DockLayoutExample(css_path="dock_layout3_sidebar_header.css")
if __name__ == "__main__":
app = DockLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout1.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout1.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout1.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout2.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout1.css"
def compose(self) -> ComposeResult:
yield Static("Oneeee", classes="box")
yield Static("Two", classes="box")
@@ -13,6 +15,6 @@ class GridLayoutExample(App):
yield Static("Seven", classes="box")
app = GridLayoutExample(css_path="grid_layout1.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout3_row_col_adjust.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout3_row_col_adjust.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout3_row_col_adjust.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout4_row_col_adjust.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout4_row_col_adjust.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout4_row_col_adjust.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout5_col_span.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout5_col_span.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two [b](column-span: 2)", classes="box", id="two")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout5_col_span.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/grid_layout6_row_span.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout6_row_span.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two [b](column-span: 2 and row-span: 2)", classes="box", id="two")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout6_row_span.css")
app = GridLayoutExample()
if __name__ == "__main__":
app.run()

4
docs/examples/guide/layout/grid_layout7_gutter.py
View File

@@ -3,6 +3,8 @@ from textual.widgets import Static
class GridLayoutExample(App):
CSS_PATH = "grid_layout7_gutter.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
@@ -12,6 +14,6 @@ class GridLayoutExample(App):
yield Static("Six", classes="box")
app = GridLayoutExample(css_path="grid_layout7_gutter.css")
if __name__ == "__main__":
app = GridLayoutExample()
app.run()

4
docs/examples/guide/layout/horizontal_layout.py
View File

@@ -3,12 +3,14 @@ from textual.widgets import Static
class HorizontalLayoutExample(App):
CSS_PATH = "horizontal_layout.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
yield Static("Three", classes="box")
app = HorizontalLayoutExample(css_path="horizontal_layout.css")
if __name__ == "__main__":
app = HorizontalLayoutExample()
app.run()

4
docs/examples/guide/layout/horizontal_layout_overflow.py
View File

@@ -3,12 +3,14 @@ from textual.widgets import Static
class HorizontalLayoutExample(App):
CSS_PATH = "horizontal_layout_overflow.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
yield Static("Three", classes="box")
app = HorizontalLayoutExample(css_path="horizontal_layout_overflow.css")
if __name__ == "__main__":
app = HorizontalLayoutExample()
app.run()

4
docs/examples/guide/layout/layers.py
View File

@@ -3,11 +3,13 @@ from textual.widgets import Static
class LayersExample(App):
CSS_PATH = "layers.css"
def compose(self) -> ComposeResult:
yield Static("box1 (layer = above)", id="box1")
yield Static("box2 (layer = below)", id="box2")
app = LayersExample(css_path="layers.css")
if __name__ == "__main__":
app = LayersExample()
app.run()

4
docs/examples/guide/layout/offset.py
View File

@@ -12,6 +12,8 @@ class Box(Static):
class OffsetExample(App):
CSS_PATH = "offset.css"
def compose(self) -> ComposeResult:
yield layout.Container(
Box(id="box1"),
@@ -22,6 +24,6 @@ class OffsetExample(App):
)
app = OffsetExample(css_path="offset.css")
if __name__ == "__main__":
app = OffsetExample()
app.run()

4
docs/examples/guide/layout/utility_containers.py
View File

@@ -4,6 +4,8 @@ from textual.widgets import Static
class UtilityContainersExample(App):
CSS_PATH = "utility_containers.css"
def compose(self) -> ComposeResult:
yield layout.Horizontal(
layout.Vertical(
@@ -19,6 +21,6 @@ class UtilityContainersExample(App):
)
app = UtilityContainersExample(css_path="utility_containers.css")
if __name__ == "__main__":
app = UtilityContainersExample()
app.run()

4
docs/examples/guide/layout/vertical_layout.py
View File

@@ -3,12 +3,14 @@ from textual.widgets import Static
class VerticalLayoutExample(App):
CSS_PATH = "vertical_layout.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
yield Static("Three", classes="box")
app = VerticalLayoutExample(css_path="vertical_layout.css")
if __name__ == "__main__":
app = VerticalLayoutExample()
app.run()

4
docs/examples/guide/layout/vertical_layout_scrolled.py
View File

@@ -3,12 +3,14 @@ from textual.widgets import Static
class VerticalLayoutScrolledExample(App):
CSS_PATH = "vertical_layout_scrolled.css"
def compose(self) -> ComposeResult:
yield Static("One", classes="box")
yield Static("Two", classes="box")
yield Static("Three", classes="box")
app = VerticalLayoutScrolledExample(css_path="vertical_layout_scrolled.css")
if __name__ == "__main__":
app = VerticalLayoutScrolledExample()
app.run()

2
docs/examples/guide/structure.py
View File

@@ -25,6 +25,6 @@ class ClockApp(App):
yield Clock()
app = ClockApp()
if __name__ == "__main__":
app = ClockApp()
app.run()

2
docs/examples/guide/styles/border01.py
View File

@@ -22,6 +22,6 @@ class BorderApp(App):
self.widget.styles.border = ("heavy", "yellow")
app = BorderApp()
if __name__ == "__main__":
app = BorderApp()
app.run()

2
docs/examples/guide/styles/box_sizing01.py
View File

@@ -33,6 +33,6 @@ class BoxSizing(App):
self.widget2.styles.box_sizing = "content-box"
app = BoxSizing()
if __name__ == "__main__":
app = BoxSizing()
app.run()

2
docs/examples/guide/styles/colors.py
View File

@@ -12,6 +12,6 @@ class WidgetApp(App):
self.widget.styles.border = ("heavy", "white")
app = WidgetApp()
if __name__ == "__main__":
app = WidgetApp()
app.run()

2
docs/examples/guide/styles/colors01.py
View File

@@ -19,6 +19,6 @@ class ColorApp(App):
self.widget3.styles.background = Color(191, 78, 96)
app = ColorApp()
if __name__ == "__main__":
app = ColorApp()
app.run()

2
docs/examples/guide/styles/colors02.py
View File

@@ -15,6 +15,6 @@ class ColorApp(App):
widget.styles.background = Color(191, 78, 96, a=alpha)
app = ColorApp()
if __name__ == "__main__":
app = ColorApp()
app.run()

2
docs/examples/guide/styles/dimensions01.py
View File

@@ -22,6 +22,6 @@ class DimensionsApp(App):
self.widget.styles.height = 10
app = DimensionsApp()
if __name__ == "__main__":
app = DimensionsApp()
app.run()

2
docs/examples/guide/styles/dimensions02.py
View File

@@ -22,6 +22,6 @@ class DimensionsApp(App):
self.widget.styles.height = "auto"
app = DimensionsApp()
if __name__ == "__main__":
app = DimensionsApp()
app.run()

2
docs/examples/guide/styles/dimensions03.py
View File

@@ -22,6 +22,6 @@ class DimensionsApp(App):
self.widget.styles.height = "80%"
app = DimensionsApp()
if __name__ == "__main__":
app = DimensionsApp()
app.run()

2
docs/examples/guide/styles/dimensions04.py
View File

@@ -25,6 +25,6 @@ class DimensionsApp(App):
self.widget2.styles.height = "1fr"
app = DimensionsApp()
if __name__ == "__main__":
app = DimensionsApp()
app.run()

2
docs/examples/guide/styles/margin01.py
View File

@@ -27,6 +27,6 @@ class MarginApp(App):
self.widget2.styles.margin = 2
app = MarginApp()
if __name__ == "__main__":
app = MarginApp()
app.run()

2
docs/examples/guide/styles/outline01.py
View File

@@ -22,6 +22,6 @@ class OutlineApp(App):
self.widget.styles.outline = ("heavy", "yellow")
app = OutlineApp()
if __name__ == "__main__":
app = OutlineApp()
app.run()

2
docs/examples/guide/styles/padding01.py
View File

@@ -22,6 +22,6 @@ class PaddingApp(App):
self.widget.styles.padding = 2
app = PaddingApp()
if __name__ == "__main__":
app = PaddingApp()
app.run()

2
docs/examples/guide/styles/padding02.py
View File

@@ -22,6 +22,6 @@ class PaddingApp(App):
self.widget.styles.padding = (2, 4)
app = PaddingApp()
if __name__ == "__main__":
app = PaddingApp()
app.run()

2
docs/examples/guide/styles/screen.py
View File

@@ -7,6 +7,6 @@ class ScreenApp(App):
self.screen.styles.border = ("heavy", "white")
app = ScreenApp()
if __name__ == "__main__":
app = ScreenApp()
app.run()

2
docs/examples/guide/styles/widget.py
View File

@@ -12,6 +12,6 @@ class WidgetApp(App):
self.widget.styles.border = ("heavy", "white")
app = WidgetApp()
if __name__ == "__main__":
app = WidgetApp()
app.run()

19
docs/examples/light_dark.py
View File

@@ -1,19 +0,0 @@
from textual.app import App
from textual.widgets import Button
class ButtonApp(App):
DEFAULT_CSS = """
Button {
width: 100%;
}
"""
def compose(self):
yield Button("Lights off")
def on_button_pressed(self, event):
self.dark = not self.dark
self.bell()
event.button.label = "Lights ON" if self.dark else "Lights OFF"

14
docs/examples/simple.css
View File

@@ -1,14 +0,0 @@
Screen {
background: darkblue;
color: white;
layout: vertical;
align: center middle;
}
Static {
height: auto;
padding: 2;
margin: 2;
border: white;
background: #ffffff 30%;
content-align: center middle;
}

11
docs/examples/simple.py
View File

@@ -1,11 +0,0 @@
from textual.app import App, ComposeResult
from textual.widgets import Static
class TextApp(App):
def compose(self) -> ComposeResult:
yield Static("Hello")
yield Static("[b]World![/b]")
app = TextApp(css_path="simple.css")

4
docs/examples/tutorial/stopwatch.py
View File

@@ -71,6 +71,8 @@ class Stopwatch(Static):
class StopwatchApp(App):
"""A Textual app to manage stopwatches."""
CSS_PATH = "stopwatch.css"
BINDINGS = [
("d", "toggle_dark", "Toggle dark mode"),
("a", "add_stopwatch", "Add"),
@@ -100,6 +102,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp(css_path="stopwatch.css")
if __name__ == "__main__":
app = StopwatchApp()
app.run()

2
docs/examples/tutorial/stopwatch01.py
View File

@@ -17,6 +17,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp()
if __name__ == "__main__":
app = StopwatchApp()
app.run()

2
docs/examples/tutorial/stopwatch02.py
View File

@@ -34,6 +34,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp()
if __name__ == "__main__":
app = StopwatchApp()
app.run()

3
docs/examples/tutorial/stopwatch03.py
View File

@@ -21,6 +21,7 @@ class Stopwatch(Static):
class StopwatchApp(App):
"""A Textual app to manage stopwatches."""
CSS_PATH = "stopwatch03.css"
BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]
def compose(self) -> ComposeResult:
@@ -34,6 +35,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp(css_path="stopwatch03.css")
if __name__ == "__main__":
app = StopwatchApp()
app.run()

3
docs/examples/tutorial/stopwatch04.py
View File

@@ -28,6 +28,7 @@ class Stopwatch(Static):
class StopwatchApp(App):
"""A Textual app to manage stopwatches."""
CSS_PATH = "stopwatch04.css"
BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]
def compose(self) -> ComposeResult:
@@ -41,6 +42,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp(css_path="stopwatch04.css")
if __name__ == "__main__":
app = StopwatchApp()
app.run()

3
docs/examples/tutorial/stopwatch05.py
View File

@@ -48,6 +48,7 @@ class Stopwatch(Static):
class StopwatchApp(App):
"""A Textual app to manage stopwatches."""
CSS_PATH = "stopwatch04.css"
BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]
def compose(self) -> ComposeResult:
@@ -61,6 +62,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp(css_path="stopwatch04.css")
if __name__ == "__main__":
app = StopwatchApp()
app.run()

3
docs/examples/tutorial/stopwatch06.py
View File

@@ -71,6 +71,7 @@ class Stopwatch(Static):
class StopwatchApp(App):
"""A Textual app to manage stopwatches."""
CSS_PATH = "stopwatch04.css"
BINDINGS = [("d", "toggle_dark", "Toggle dark mode")]
def compose(self) -> ComposeResult:
@@ -84,6 +85,6 @@ class StopwatchApp(App):
self.dark = not self.dark
app = StopwatchApp(css_path="stopwatch04.css")
if __name__ == "__main__":
app = StopwatchApp()
app.run()

12
docs/examples/widgets/button.py
View File

@@ -3,7 +3,9 @@ from textual.app import App, ComposeResult
from textual.widgets import Button, Static
class ButtonsApp(App):
class ButtonsApp(App[str]):
CSS_PATH = "button.css"
def compose(self) -> ComposeResult:
yield layout.Horizontal(
layout.Vertical(
@@ -24,11 +26,11 @@ class ButtonsApp(App):
),
)
def on_button_pressed(self, _event: Button.Pressed) -> None:
def on_button_pressed(self, event: Button.Pressed) -> None:
self.app.bell()
self.exit(str(event.button))
app = ButtonsApp(css_path="button.css")
if __name__ == "__main__":
result = app.run()
app = ButtonsApp()
print(app.run())

2
docs/getting_started.md
View File

@@ -2,7 +2,7 @@ All you need to get started building Textual apps.
## Requirements
Textual requires Python 3.7 or later. Textual runs on Linux, MacOS, Windows and probably any OS where Python also runs.
Textual requires Python 3.7 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, MacOS, Windows and probably any OS where Python also runs.
!!! info inline end "Your platform"

8
docs/guide/CSS.md
View File

@@ -111,7 +111,7 @@ Both Header and Footer are children of the Screen object.
To further explore the DOM, we're going to build a simple dialog with a question and two buttons. To do this we're going import and use a few more builtin widgets:
- `texual.layout.Container` For our top-level dialog.
- `textual.layout.Container` For our top-level dialog.
- `textual.layout.Horizontal` To arrange widgets left to right.
- `textual.widgets.Static` For simple content.
- `textual.widgets.Button` For a clickable button.
@@ -140,13 +140,13 @@ You may recognize some of the elements in the above screenshot, but it doesn't q
## CSS files
To add a stylesheet we pass the path to the app with the `css_path` parameter:
To add a stylesheet set the `CSS_PATH` classvar to a relative path:
```python hl_lines="23"
```python hl_lines="9"
--8<-- "docs/examples/guide/dom4.py"
```
You may have noticed that some of the constructors have additional keyword argument: `id` and `classes`. These are used by the CSS to identify parts of the DOM. We will cover these in the next section.
You may have noticed that some of the constructors have additional keyword arguments: `id` and `classes`. These are used by the CSS to identify parts of the DOM. We will cover these in the next section.
Here's the CSS file we are applying:

9
docs/guide/app.md
View File

@@ -10,6 +10,7 @@ The first step in building a Textual app is to import the [App][textual.app.App]
--8<-- "docs/examples/app/simple01.py"
```
### The run method
To run an app we create an instance and call [run()][textual.app.App.run].
@@ -153,9 +154,9 @@ Textual apps can reference [CSS](CSS.md) files which define how your app and wid
The chapter on [Textual CSS](CSS.md) describes how to use CSS in detail. For now lets look at how your app references external CSS files.
The following example sets the `css_path` attribute on the app:
The following example enables loading of CSS by adding a `CSS_PATH` class variable:
```python title="question02.py" hl_lines="15"
```python title="question02.py" hl_lines="6"
--8<-- "docs/examples/app/question02.py"
```
@@ -172,7 +173,9 @@ When `"question02.py"` runs it will load `"question02.css"` and update the app a
### Classvar CSS
While external CSS files are recommended for most applications, and enable some cool features like *live editing* (see below), you can also specify the CSS directly within the Python code. To do this you can set the `CSS` class variable on the app which contains the CSS content.
While external CSS files are recommended for most applications, and enable some cool features like *live editing*, you can also specify the CSS directly within the Python code.
To do this set a `CSS` class variable on the app to a string containing your CSS.
Here's the question app with classvar CSS:

3
docs/guide/devtools.md
View File

@@ -118,9 +118,8 @@ class LogApp(App):
def on_mount(self):
self.log(self.tree)
app = LogApp()
if __name__ == "__main__":
app.run()
LogApp.run()
```

192
docs/guide/events.md
View File

@@ -1,13 +1,189 @@
## Events
# Events and Messages
TODO: events docs
We've used event handler methods in many of the examples in this guide. This chapter explores [events](../events/index.md) and messages (see below) in more detail.
- What are events
- Handling events
- Auto calling base classes
- Event bubbling
- Posting / emitting events
## Messages
Events are a particular kind of *message* sent by Textual in response to input and other state changes. Events are reserved for use by Textual but you can also create custom messages for the purpose of coordinating between widgets in your app.
More on that later, but for now keep in mind that events are also messages, and anything that is true of messages is true of events.
## Message Queue
Every [App][textual.app.App] and [Widget][textual.widget.Widget] object contains a *message queue*. You can think of a message queue as orders at a restaurant. The chef takes an order and makes the dish. Orders that arrive while the chef is cooking are placed in a line. When the chef has finished a dish they pick up the next order in the line.
Textual processes messages in the same way. Messages are picked off a queue and processed (cooked) by a handler method. This guarantees messages and events are processed even if your code can not handle them right way.
This processing of messages is done within an asyncio Task which is started when you mount the widget. The task monitors a queue for new messages and dispatches them to the appropriate handler when they arrive.
!!! tip
The FastAPI docs have an [excellent introduction](https://fastapi.tiangolo.com/async/) to Python async programming.
By way of an example, let's consider what happens if you were to type "Text" in to a `TextInput` widget. When you hit the ++t++ key, Textual creates a [key][textual.events.Key] event and sends it to the widget's message queue. Ditto for ++e++, ++x++, and ++t++.
The widget's task will pick the first message from the queue (a key event for the ++t++ key) and call the `on_key` method with the event as the first argument. In other words it will call `TextInput.on_key(event)`, which updates the display to show the new letter.
<div class="excalidraw">
--8<-- "docs/images/test.excalidraw.svg"
--8<-- "docs/images/events/queue.excalidraw.svg"
</div>
When the `on_key` method returns, Textual will get the next event from the the queue and repeat the process for the remaining keys. At some point the queue will be empty and the widget is said to be in an *idle* state.
!!! note
This example illustrates a point, but a typical app will be fast enough to have processed a key before the next event arrives. So it is unlikely you will have so many key events in the message queue.
<div class="excalidraw">
--8<-- "docs/images/events/queue2.excalidraw.svg"
</div>
## Default behaviors
You may be familiar with Python's [super](https://docs.python.org/3/library/functions.html#super) function to call a function defined in a base class. You will not have to use this in event handlers as Textual will automatically call handler methods defined in a widget's base class(es).
For instance, let's say we are building the classic game of Pong and we have written a `Paddle` widget which extends [Static][textual.widgets.Static]. When a [Key][textual.events.Key] event arrives, Textual calls `Paddle.on_key` (to respond to ++left++ and ++right++ keys), then `Static.on_key`, and finally `Widget.on_key`.
### Preventing default behaviors
If you don't want this behavior you can call [prevent_default()][textual.message.Message.prevent_default] on the event object. This tells Textual not to call any more handlers on base classes.
!!! warning
You won't need `prevent_default` very often. Be sure to know what your base classes do before calling it, or you risk disabling some core features builtin to Textual.
## Bubbling
Messages have a `bubble` attribute. If this is set to `True` then events will be sent to a widget's parent after processing. Input events typically bubble so that a widget will have the opportunity to respond to input events if they aren't handled by their children.
The following diagram shows an (abbreviated) DOM for a UI with a container and two buttons. With the "No" button [focused](#), it will receive the key event first.
<div class="excalidraw">
--8<-- "docs/images/events/bubble1.excalidraw.svg"
</div>
After Textual calls `Button.on_key` the event _bubbles_ to the button's parent and will call `Container.on_key` (if it exists).
<div class="excalidraw">
--8<-- "docs/images/events/bubble2.excalidraw.svg"
</div>
As before, the event bubbles to it's parent (the App class).
<div class="excalidraw">
--8<-- "docs/images/events/bubble3.excalidraw.svg"
</div>
The App class is always the root of the DOM, so there is no where for the event to bubble to.
### Stopping bubbling
Event handlers may stop this bubble behavior by calling the [stop()][textual.message.Message.stop] method on the event or message. You might want to do this if a widget has responded to the event in an authoritative way. For instance when a text input widget responds to a key event it stops the bubbling so that the key doesn't also invoke a key binding.
## Custom messages
You can create custom messages for your application that may be used in the same way as events (recall that events are simply messages reserved for use by Textual).
The most common reason to do this is if you are building a custom widget and you need to inform a parent widget about a state change.
Let's look at an example which defines a custom message. The following example creates color buttons which&mdash;when clicked&mdash;send a custom message.
=== "custom01.py"
```python title="custom01.py" hl_lines="10-15 27-29 42-43"
--8<-- "docs/examples/events/custom01.py"
```
=== "Output"
```{.textual path="docs/examples/events/custom01.py"}
```
Note the custom message class which extends [Message][textual.message.Message]. The constructor stores a [color][textual.color.Color] object which handler methods will be able to inspect.
The message class is defined within the widget class itself. This is not strictly required but recommended, for these reasons:
- It reduces the amount of imports. If you import `ColorButton`, you have access to the message class via `ColorButton.Selected`.
- It creates a namespace for the handler. So rather than `on_selected`, the handler name becomes `on_color_button_selected`. This makes it less likely that your chosen name will clash with another message.
## Sending events
In the previous example we used [emit()][textual.message_pump.MessagePump.emit] to send an event to it's parent. We could also have used [emit_no_wait()][textual.message_pump.MessagePump.emit_no_wait] for non async code. Sending messages in this way allows you to write custom widgets without needing to know in what context they will be used.
There are other ways of sending (posting) messages, which you may need to use less frequently.
- [post_message][textual.message_pump.MessagePump.post_message] To post a message to a particular widget.
- [post_message_no_wait][textual.message_pump.MessagePump.post_message_no_wait] The non-async version of `post_message`.
## Message handlers
Most of the logic in a Textual app will be written in message handlers. Let's explore handlers in more detail.
### Handler naming
Textual uses the following scheme to map messages classes on to a Python method.
- Start with `"on_"`.
- Add the messages namespace (if any) converted from CamelCase to snake_case plus an underscore `"_"`
- Add the name of the class converted from CamelCase to snake_case.
<div class="excalidraw">
--8<-- "docs/images/events/naming.excalidraw.svg"
</div>
### Handler arguments
Message handler methods can be written with or without a positional argument. If you add a positional argument, Textual will call the handler with the event object. The following handler (taken from custom01.py above) contains a `message` parameter. The body of the code makes use of the message to set a preset color.
```python
def on_color_button_selected(self, message: ColorButton.Selected) -> None:
self.screen.styles.animate("background", message.color, duration=0.5)
```
If the body of your handler doesn't require any information in the message you can omit it from the method signature. If we just want to play a bell noise when the button is clicked, we could write our handler like this:
```python
def on_color_button_selected(self) -> None:
self.app.bell()
```
This pattern is a convenience that saves writing out a parameter that may not be used.
### Async handlers
Message handlers may be coroutines. If you prefix your handlers with the `async` keyword, Textual will `await` them. This lets your handler use the `await` keyword for asynchronous APIs.
If your event handlers are coroutines it will allow multiple events to be processed concurrently, but bear in mind an individual widget (or app) will not be able to pick up a new message from its message queue until the handler has returned. This is rarely a problem in practice; as long has handlers return within a few milliseconds the UI will remain responsive. But slow handlers might make your app hard to use.
!!! info
To re-use the chef analogy, if an order comes in for beef wellington (which takes a while to cook), orders may start to pile up and customers may have to wait for their meal. The solution would be to have another chef work on the wellington while the first chef picks up new orders.
Network access is a common cause of slow handlers. If you try to retrieve a file from the internet, the message handler may take anything up to a few seconds to return, which would prevent the widget or app from updating during that time. The solution is to launch a new asyncio task to do the network task in the background.
Let's look at an example which looks up word definitions from an [api](https://dictionaryapi.dev/) as you type.
!!! note
You will need to install [httpx](https://www.python-httpx.org/) with `pip install httpx` to run this example.
=== "dictionary.py"
```python title="dictionary.py" hl_lines="28"
--8<-- "docs/examples/events/dictionary.py"
```
=== "dictionary.css"
```python title="dictionary.css"
--8<-- "docs/examples/events/dictionary.css"
```
=== "Output"
```{.textual path="docs/examples/events/dictionary.py" press="tab,t,e,x,t,_,_,_,_,_,_,_,_,_,_,_"}
```
Note the highlighted line in the above code which calls `asyncio.create_task` to run coroutine in the background. Without this you would find typing in to the text box to be unresponsive.

2
docs/guide/styles.md
View File

@@ -206,7 +206,7 @@ The same units may also be used to set limits on a dimension. The following styl
- [min-width](../styles/min_width.md) sets a minimum width.
- [max-width](../styles/max_width.md) sets a maximum width.
- [min-height](../styles/min_height.md) sets a minimum height.
- [max-height](../styles/max_hright.md) sets a maximum height.
- [max-height](../styles/max_height.md) sets a maximum height.
### Padding

16
docs/images/events/bubble1.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

16
docs/images/events/bubble2.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

16
docs/images/events/bubble3.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

16
docs/images/events/naming.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

16
docs/images/events/queue.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

16
docs/images/events/queue2.excalidraw.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 90 KiB

16
docs/images/test.excalidraw.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 48 KiB

5
docs/index.md
View File

@@ -59,7 +59,7 @@ Textual is a framework for building applications that run within your terminal.
<hr>
```{.textual path="examples/calculator.py" columns=100 lines=40}
```{.textual path="examples/calculator.py" columns=100 lines=41 press="3,.,1,4,5,9,2,_,_"}
```
@@ -70,6 +70,9 @@ Textual is a framework for building applications that run within your terminal.
```{.textual path="docs/examples/tutorial/stopwatch.py" press="tab,enter,_,_"}
```
```{.textual path="docs/examples/guide/layout/combining_layouts.py"}
```
```{.textual path="docs/examples/app/widgets01.py"}
```

1
docs/reference/message.md Normal file
View File

@@ -0,0 +1 @@
::: textual.message.Message

1
docs/reference/static.md Normal file
View File

@@ -0,0 +1 @@
::: textual.widgets.Static

10
docs/tutorial.md
View File

@@ -6,7 +6,7 @@ By the end of this page you should have a solid understanding of app development
!!! quote
I've always thought the secret sauce in making a popular framework is for it to be fun.
If you want people to build things, make it fun.
&mdash; **Will McGugan** (creator of Rich and Textual)
@@ -200,11 +200,11 @@ While it's possible to set all styles for an app this way, it is rarely necessar
Let's add a CSS file to our application.
```python title="stopwatch03.py" hl_lines="37"
```python title="stopwatch03.py" hl_lines="24"
--8<-- "docs/examples/tutorial/stopwatch03.py"
```
Adding the `css_path` attribute to the app constructor tells Textual to load the following file when it starts the app:
Adding the `CSS_PATH` class variable tells Textual to load the following file when it starts the app:
```sass title="stopwatch03.css"
--8<-- "docs/examples/tutorial/stopwatch03.css"
@@ -329,7 +329,7 @@ The `on_button_pressed` method is an *event handler*. Event handlers are methods
If you run "stopwatch04.py" now you will be able to toggle between the two states by clicking the first button:
```{.textual path="docs/examples/tutorial/stopwatch04.py" title="stopwatch04.py" press="tab,tab,tab,enter,_,_"}
```{.textual path="docs/examples/tutorial/stopwatch04.py" title="stopwatch04.py" press="tab,tab,tab,_,enter,_,_,_"}
```
## Reactive attributes
@@ -423,7 +423,7 @@ To add a new child widget call `mount()` on the parent. To remove a widget, call
Let's use these to implement adding and removing stopwatches to our app.
```python title="stopwatch.py" hl_lines="76-77 86-90 92-96"
```python title="stopwatch.py" hl_lines="78-79 88-92 94-98"
--8<-- "docs/examples/tutorial/stopwatch.py"
```

7
e2e_tests/test_apps/basic.py
View File

@@ -104,9 +104,11 @@ class Success(Widget):
return Text("This is a success message", justify="center")
class BasicApp(App, css_path="basic.css"):
class BasicApp(App):
"""A basic app demonstrating CSS"""
CSS_PATH = "basic.css"
def on_load(self):
"""Bind keys here."""
self.bind("s", "toggle_class('#sidebar', '-active')", description="Sidebar")
@@ -210,9 +212,8 @@ class BasicApp(App, css_path="basic.css"):
self.bell()
app = BasicApp()
if __name__ == "__main__":
app = BasicApp()
app.run(quit_after=2)
# from textual.geometry import Region

29
examples/borders.py
View File

@@ -1,29 +0,0 @@
from itertools import cycle
from textual.app import App
from textual.color import Color
from textual.constants import BORDERS
from textual.widgets import Static
class BorderApp(App):
"""Displays a pride flag."""
COLORS = ["red", "orange", "yellow", "green", "blue", "purple"]
def compose(self):
self.dark = True
for border, color in zip(BORDERS, cycle(self.COLORS)):
static = Static(f"border: {border} {color};")
static.styles.height = 7
static.styles.background = Color.parse(color).with_alpha(0.2)
static.styles.margin = (1, 2)
static.styles.border = (border, color)
static.styles.content_align = ("center", "middle")
yield static
app = BorderApp()
if __name__ == "__main__":
app.run()

5
examples/calculator.py
View File

@@ -10,6 +10,8 @@ from textual.widgets import Button, Static
class CalculatorApp(App):
"""A working 'desktop' calculator."""
CSS_PATH = "calculator.css"
numbers = var("0")
show_ac = var(True)
left = var(Decimal("0"))
@@ -137,6 +139,5 @@ class CalculatorApp(App):
do_math()
app = CalculatorApp(css_path="calculator.css")
if __name__ == "__main__":
app.run()
CalculatorApp().run()

4
examples/code_browser.css
View File

@@ -16,10 +16,6 @@ CodeBrowser.-show-tree #tree-view {
background: $surface;
}
CodeBrowser{
background: $background;
}
DirectoryTree {
padding-right: 1;
padding-right: 1;

4
examples/code_browser.py
View File

@@ -12,6 +12,7 @@ from textual.widgets import DirectoryTree, Footer, Header, Static
class CodeBrowser(App):
"""Textual code browser app."""
CSS_PATH = "code_browser.css"
BINDINGS = [
("f", "toggle_files", "Toggle Files"),
("q", "quit", "Quit"),
@@ -56,6 +57,5 @@ class CodeBrowser(App):
self.show_tree = not self.show_tree
app = CodeBrowser(css_path="code_browser.css")
if __name__ == "__main__":
app.run()
CodeBrowser().run()

4
examples/pride.py
View File

@@ -15,7 +15,5 @@ class PrideApp(App):
yield stripe
app = PrideApp()
if __name__ == "__main__":
app.run()
PrideApp().run()

8
mkdocs.yml
View File

@@ -92,16 +92,20 @@ nav:
- "widgets/text_input.md"
- "widgets/tree_control.md"
- Reference:
- "reference/index.md"
- "reference/app.md"
- "reference/button.md"
- "reference/color.md"
- "reference/dom_node.md"
- "reference/events.md"
- "reference/geometry.md"
- "reference/index.md"
- "reference/message_pump.md"
- "reference/timer.md"
- "reference/message.md"
- "reference/query.md"
- "reference/reactive.md"
- "reference/screen.md"
- "reference/static.md"
- "reference/timer.md"
- "reference/widget.md"

11
old examples/README.md
View File

@@ -1,11 +0,0 @@
These examples probably don't rub. We will be back-porting them to the examples dir
# Examples
Run any of these examples to demonstrate a Textual features.
The example code will generate a log file called "textual.log". Tail this file to gain insight in to what Textual is doing.
```
tail -f textual
```

38
old examples/animation.py
View File

@@ -1,38 +0,0 @@
from textual.app import App
from textual.reactive import Reactive
from textual.widgets import Footer, Placeholder
class SmoothApp(App):
"""Demonstrates smooth animation. Press 'b' to see it in action."""
async def on_load(self) -> None:
"""Bind keys here."""
await self.bind("b", "toggle_sidebar", "Toggle sidebar")
await self.bind("q", "quit", "Quit")
show_bar = Reactive(False)
def watch_show_bar(self, show_bar: bool) -> None:
"""Called when show_bar changes."""
self.bar.animate("layout_offset_x", 0 if show_bar else -40)
def action_toggle_sidebar(self) -> None:
"""Called when user hits 'b' key."""
self.show_bar = not self.show_bar
async def on_mount(self) -> None:
"""Build layout here."""
footer = Footer()
self.bar = Placeholder(name="left")
await self.screen.dock(footer, edge="bottom")
await self.screen.dock(Placeholder(), Placeholder(), edge="top")
await self.screen.dock(self.bar, edge="left", size=40, z=1)
self.bar.layout_offset_x = -40
# self.set_timer(10, lambda: self.action("quit"))
SmoothApp.run(log_path="textual.log")

33
old examples/big_table.py
View File

@@ -1,33 +0,0 @@
from rich.table import Table
from textual import events
from textual.app import App
from textual.widgets import ScrollView
class MyApp(App):
"""An example of a very simple Textual App"""
async def on_load(self, event: events.Load) -> None:
await self.bind("q", "quit", "Quit")
async def on_mount(self, event: events.Mount) -> None:
self.body = body = ScrollView(auto_width=True)
await self.screen.dock(body)
async def add_content():
table = Table(title="Demo")
for i in range(20):
table.add_column(f"Col {i + 1}", style="magenta")
for i in range(100):
table.add_row(*[f"cell {i},{j}" for j in range(20)])
await body.update(table)
await self.call_later(add_content)
MyApp.run(title="Simple App", log_path="textual.log")

59
old examples/borders.css
View File

@@ -1,59 +0,0 @@
Screen {
/* text-background: #212121; */
}
#borders {
layout: vertical;
background: #212121;
overflow-y: scroll;
}
Lorem.border {
height: 12;
margin: 2 4;
background: #303f9f;
}
Lorem.round {
border: round #8bc34a;
}
Lorem.solid {
border: solid #8bc34a;
}
Lorem.double {
border: double #8bc34a;
}
Lorem.dashed {
border: dashed #8bc34a;
}
Lorem.heavy {
border: heavy #8bc34a;
}
Lorem.inner {
border: inner #8bc34a;
}
Lorem.outer {
border: outer #8bc34a;
}
Lorem.hkey {
border: hkey #8bc34a;
}
Lorem.vkey {
border: vkey #8bc34a;
}
Lorem.tall {
border: tall #8bc34a;
}
Lorem.wide {
border: wide #8bc34a;
}

57
old examples/borders.py
View File

@@ -1,57 +0,0 @@
from rich.padding import Padding
from rich.style import Style
from rich.text import Text
from textual.app import App
from textual.renderables.gradient import VerticalGradient
from textual.widget import Widget
lorem = Text.from_markup(
"""[#C5CAE9]Lorem ipsum dolor sit amet, consectetur adipiscing elit. In velit libero, volutpat nec hendrerit at, faucibus in odio. Aliquam hendrerit nibh sed quam volutpat maximus. Nullam suscipit convallis lorem quis sodales. In tristique lobortis ante et dictum. Ut at finibus ipsum. In urna dolor, placerat et mi facilisis, congue sollicitudin massa. Phasellus felis turpis, cursus eu lectus et, porttitor malesuada augue. Sed feugiat volutpat velit, sollicitudin fringilla velit bibendum faucibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In velit libero, volutpat nec hendrerit at, faucibus in odio. Aliquam hendrerit nibh sed quam volutpat maximus. Nullam suscipit convallis lorem quis sodales. In tristique lobortis ante et dictum. Ut at finibus ipsum. In urna dolor, placerat et mi facilisis, congue sollicitudin massa. Phasellus felis turpis, cursus eu lectus et, porttitor malesuada augue. Sed feugiat volutpat velit, sollicitudin fringilla velit bibendum faucibus. """,
justify="full",
)
class Lorem(Widget):
def render(self) -> Text:
return Padding(lorem, 1)
class Background(Widget):
def render(self):
return VerticalGradient("#212121", "#212121")
class BordersApp(App):
"""Sandbox application used for testing/development by Textual developers"""
def on_load(self):
self.bind("q", "quit", "Quit")
def on_mount(self):
"""Build layout here."""
borders = [
Lorem(classes={"border", border})
for border in (
"round",
"solid",
"double",
"dashed",
"heavy",
"inner",
"outer",
"hkey",
"vkey",
"tall",
"wide",
)
]
borders_view = Background(*borders)
borders_view.show_vertical_scrollbar = True
self.mount(borders=borders_view)
app = BordersApp(css_path="borders.css", log_path="textual.log")
app.run()

216
old examples/calculator.py
View File

@@ -1,216 +0,0 @@
"""
A Textual app to create a fully working calculator, modelled after MacOS Calculator.
"""
from decimal import Decimal
from rich.align import Align
from rich.console import Console, ConsoleOptions, RenderResult, RenderableType
from rich.padding import Padding
from rich.style import Style
from rich.text import Text
from textual.app import App
from textual.reactive import Reactive
from textual.views import GridView
from textual.widget import Widget
from textual.widgets import Button
try:
from pyfiglet import Figlet
except ImportError:
print("Please install pyfiglet to run this example")
raise
class FigletText:
"""A renderable to generate figlet text that adapts to fit the container."""
def __init__(self, text: str) -> None:
self.text = text
def __rich_console__(
self, console: Console, options: ConsoleOptions
) -> RenderResult:
"""Build a Rich renderable to render the Figlet text."""
size = min(options.max_width / 2, options.max_height)
if size < 4:
yield Text(self.text, style="bold")
else:
if size < 7:
font_name = "mini"
elif size < 8:
font_name = "small"
elif size < 10:
font_name = "standard"
else:
font_name = "big"
font = Figlet(font=font_name, width=options.max_width)
yield Text(font.renderText(self.text).rstrip("\n"), style="bold")
class Numbers(Widget):
"""The digital display of the calculator."""
value = Reactive("0")
def render(self) -> RenderableType:
"""Build a Rich renderable to render the calculator display."""
return Padding(
Align.right(FigletText(self.value), vertical="middle"),
(0, 1),
style="white on rgb(51,51,51)",
)
class Calculator(GridView):
"""A working calculator app."""
DARK = "white on rgb(51,51,51)"
LIGHT = "black on rgb(165,165,165)"
YELLOW = "white on rgb(255,159,7)"
BUTTON_STYLES = {
"AC": LIGHT,
"C": LIGHT,
"+/-": LIGHT,
"%": LIGHT,
"/": YELLOW,
"X": YELLOW,
"-": YELLOW,
"+": YELLOW,
"=": YELLOW,
}
display = Reactive("0")
show_ac = Reactive(True)
def watch_display(self, value: str) -> None:
"""Called when self.display is modified."""
# self.numbers is a widget that displays the calculator result
# Setting the attribute value changes the display
# This allows us to write self.display = "100" to update the display
self.numbers.value = value
def compute_show_ac(self) -> bool:
"""Compute show_ac reactive value."""
# Condition to show AC button over C
return self.value in ("", "0") and self.display == "0"
def watch_show_ac(self, show_ac: bool) -> None:
"""When the show_ac attribute change we need to update the buttons."""
# Show AC and hide C or vice versa
self.c.display = not show_ac
self.ac.display = show_ac
def on_mount(self) -> None:
"""Event when widget is first mounted (added to a parent view)."""
# Attributes to store the current calculation
self.left = Decimal("0")
self.right = Decimal("0")
self.value = ""
self.operator = "+"
# The calculator display
self.numbers = Numbers()
self.numbers.style_border = "bold"
def make_button(text: str, style: str) -> Button:
"""Create a button with the given Figlet label."""
return Button(FigletText(text), style=style, name=text)
# Make all the buttons
self.buttons = {
name: make_button(name, self.BUTTON_STYLES.get(name, self.DARK))
for name in "+/-,%,/,7,8,9,X,4,5,6,-,1,2,3,+,.,=".split(",")
}
# Buttons that have to be treated specially
self.zero = make_button("0", self.DARK)
self.ac = make_button("AC", self.LIGHT)
self.c = make_button("C", self.LIGHT)
self.c.display = False
# Set basic grid settings
self.grid.set_gap(2, 1)
self.grid.set_gutter(1)
self.grid.set_align("center", "center")
# Create rows / columns / areas
self.grid.add_column("col", max_size=30, repeat=4)
self.grid.add_row("numbers", max_size=15)
self.grid.add_row("row", max_size=15, repeat=5)
self.grid.add_areas(
clear="col1,row1",
numbers="col1-start|col4-end,numbers",
zero="col1-start|col2-end,row5",
)
# Place out widgets in to the layout
self.grid.place(clear=self.c)
self.grid.place(
*self.buttons.values(), clear=self.ac, numbers=self.numbers, zero=self.zero
)
def handle_button_pressed(self, message: ButtonPressed) -> None:
"""A message sent by the button widget"""
assert isinstance(message.sender, Button)
button_name = message.sender.name
def do_math() -> None:
"""Does the math: LEFT OPERATOR RIGHT"""
self.log(self.left, self.operator, self.right)
try:
if self.operator == "+":
self.left += self.right
elif self.operator == "-":
self.left -= self.right
elif self.operator == "/":
self.left /= self.right
elif self.operator == "X":
self.left *= self.right
self.display = str(self.left)
self.value = ""
self.log("=", self.left)
except Exception:
self.display = "Error"
if button_name.isdigit():
self.display = self.value = self.value.lstrip("0") + button_name
elif button_name == "+/-":
self.display = self.value = str(Decimal(self.value or "0") * -1)
elif button_name == "%":
self.display = self.value = str(Decimal(self.value or "0") / Decimal(100))
elif button_name == ".":
if "." not in self.value:
self.display = self.value = (self.value or "0") + "."
elif button_name == "AC":
self.value = ""
self.left = self.right = Decimal(0)
self.operator = "+"
self.display = "0"
elif button_name == "C":
self.value = ""
self.display = "0"
elif button_name in ("+", "-", "/", "X"):
self.right = Decimal(self.value or "0")
do_math()
self.operator = button_name
elif button_name == "=":
if self.value:
self.right = Decimal(self.value)
do_math()
class CalculatorApp(App):
"""The Calculator Application"""
async def on_mount(self) -> None:
"""Mount the calculator widget."""
await self.screen.dock(Calculator())
CalculatorApp.run(title="Calculator Test", log_path="textual.log")

70
old examples/code_viewer.py
View File

@@ -1,70 +0,0 @@
import os
import sys
from rich.console import RenderableType
from rich.syntax import Syntax
from rich.traceback import Traceback
from textual.app import App
from textual.widgets import Header, Footer, FileClick, ScrollView, DirectoryTree
class MyApp(App):
"""An example of a very simple Textual App"""
async def on_load(self) -> None:
"""Sent before going in to application mode."""
# Bind our basic keys
await self.bind("b", "view.toggle('sidebar')", "Toggle sidebar")
await self.bind("q", "quit", "Quit")
# Get path to show
try:
self.path = sys.argv[1]
except IndexError:
self.path = os.path.abspath(
os.path.join(os.path.basename(__file__), "../../")
)
async def on_mount(self) -> None:
"""Call after terminal goes in to application mode"""
# Create our widgets
# In this a scroll view for the code and a directory tree
self.body = ScrollView()
self.directory = DirectoryTree(self.path, "Code")
# Dock our widgets
await self.screen.dock(Header(), edge="top")
await self.screen.dock(Footer(), edge="bottom")
# Note the directory is also in a scroll view
await self.screen.dock(
ScrollView(self.directory), edge="left", size=48, name="sidebar"
)
await self.screen.dock(self.body, edge="top")
async def handle_file_click(self, message: FileClick) -> None:
"""A message sent by the directory tree when a file is clicked."""
syntax: RenderableType
try:
# Construct a Syntax object for the path in the message
syntax = Syntax.from_path(
message.path,
line_numbers=True,
word_wrap=True,
indent_guides=True,
theme="monokai",
)
except Exception:
# Possibly a binary file
# For demonstration purposes we will show the traceback
syntax = Traceback(theme="monokai", width=None, show_locals=True)
self.app.sub_title = os.path.basename(message.path)
await self.body.update(syntax)
# Run our app class
MyApp.run(title="Code Viewer", log_path="textual.log")

10
old examples/colours.txt
View File

@@ -1,10 +0,0 @@
header blue white on #173f5f
sidebar #09312e on #3caea3
sidebar border #09312e
content blue white #20639b
content border #0f2b41
footer border #0f2b41
footer yellow #3a3009 on #f6d55c;

45
old examples/easing.py
View File

@@ -1,45 +0,0 @@
from textual._easing import EASING
from textual.app import App
from textual.reactive import Reactive
from textual.views import DockView
from textual.widgets import Placeholder, TreeControl, ScrollView, TreeClick
class EasingApp(App):
"""An app do demonstrate easing."""
side = Reactive(False)
easing = Reactive("linear")
def watch_side(self, side: bool) -> None:
"""Animate when the side changes (False for left, True for right)."""
width = self.easing_view.outer_size.width
animate_x = (width - self.placeholder.outer_size.width) if side else 0
self.placeholder.animate(
"layout_offset_x", animate_x, easing=self.easing, duration=1
)
async def on_mount(self) -> None:
"""Called when application mode is ready."""
self.placeholder = Placeholder()
self.easing_view = DockView()
self.placeholder.style = "white on dark_blue"
tree = TreeControl("Easing", {})
for easing_key in sorted(EASING.keys()):
await tree.add(tree.root.id, easing_key, {"easing": easing_key})
await tree.root.expand()
await self.screen.dock(ScrollView(tree), edge="left", size=32)
await self.screen.dock(self.easing_view)
await self.easing_view.dock(self.placeholder, edge="left", size=32)
async def handle_tree_click(self, message: TreeClick[dict]) -> None:
"""Called in response to a tree click."""
self.easing = message.node.data.get("easing", "linear")
self.side = not self.side
EasingApp().run(log_path="textual.log")

34
old examples/example.css
View File

@@ -1,34 +0,0 @@
App > View {
layout: dock;
docks: side=left/1;
}
#header {
text: on #173f5f;
height: 3;
border: hkey white;
}
#content {
text: on #20639b;
}
#footer {
height: 3;
border-top: hkey #0f2b41;
text: #3a3009 on #f6d55c;
}
#sidebar {
text: #09312e on #3caea3;
dock: side;
width: 30;
border-right: outer #09312e;
offset-x: -100%;
transition: offset 400ms in_out_cubic;
}
#sidebar.-active {
offset-x: 0;
transition: offset 400ms in_out_cubic;
}

34
old examples/grid.py
View File

@@ -1,34 +0,0 @@
from textual.app import App
from textual.widgets import Placeholder
class GridTest(App):
async def on_mount(self) -> None:
"""Make a simple grid arrangement."""
grid = await self.screen.dock_grid(edge="left", name="left")
grid.add_column(fraction=1, name="left", min_size=20)
grid.add_column(size=30, name="center")
grid.add_column(fraction=1, name="right")
grid.add_row(fraction=1, name="top", min_size=2)
grid.add_row(fraction=2, name="middle")
grid.add_row(fraction=1, name="bottom")
grid.add_areas(
area1="left,top",
area2="center,middle",
area3="left-start|right-end,bottom",
area4="right,top-start|middle-end",
)
grid.place(
area1=Placeholder(name="area1"),
area2=Placeholder(name="area2"),
area3=Placeholder(name="area3"),
area4=Placeholder(name="area4"),
)
GridTest.run(title="Grid Test", log_path="textual.log")

Some files were not shown because too many files have changed in this diff Show More