renamed introduction to tutorial

docs/examples/tutorial/clock01.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+
+from textual.app import App
+from textual.widget import Widget
+
+
+class Clock(Widget):
+    def on_mount(self):
+        self.styles.content_align = ("center", "middle")
+        self.auto_refresh = 1.0
+
+    def render(self):
+        return datetime.now().strftime("%X")
+
+
+class ClockApp(App):
+    def compose(self):
+        yield Clock()
+
+
+app = ClockApp()
+app.run()

docs/examples/tutorial/clock02.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+
+from textual.app import App
+from textual.widget import Widget
+
+
+class Clock(Widget):
+    def on_mount(self):
+        self.styles.content_align = ("center", "middle")
+        self.auto_refresh = 1.0
+
+    def render(self):
+        return datetime.now().strftime("%c")
+
+
+class ClockApp(App):
+    def compose(self):
+        yield Clock()
+
+
+app = ClockApp()
+app.run()

docs/examples/tutorial/intro01.py

@@ -0,0 +1,9 @@
+from textual.app import App
+
+
+class ExampleApp(App):
+    pass
+
+
+app = ExampleApp()
+app.run()

docs/examples/tutorial/intro02.py

@@ -0,0 +1,29 @@
+from textual.app import App
+
+
+class ExampleApp(App):
+
+    COLORS = [
+        "white",
+        "maroon",
+        "red",
+        "purple",
+        "fuchsia",
+        "olive",
+        "yellow",
+        "navy",
+        "teal",
+        "aqua",
+    ]
+
+    def on_mount(self):
+        self.styles.background = "darkblue"
+
+    def on_key(self, event):
+        if event.key.isdigit():
+            self.styles.background = self.COLORS[int(event.key)]
+        self.bell()
+
+
+app = ExampleApp()
+app.run()

docs/examples/tutorial/stopwatch.css

@@ -0,0 +1,53 @@
+Stopwatch {
+    layout: horizontal;
+    background: $panel-darken-1;
+    height: 5;
+    min-width: 50;
+    margin: 1;
+    padding: 1;
+}
+
+TimeDisplay {
+    content-align: center middle;
+    text-opacity: 60%;
+    height: 3;
+}
+
+Button {
+    width: 16;
+}
+
+#start {
+    dock: left;
+}
+
+#stop {
+    dock: left;
+    display: none;
+}
+
+#reset {
+    dock: right;
+}
+
+.started {
+    text-style: bold;
+    background: $success;
+    color: $text-success;
+}
+
+.started TimeDisplay {
+    text-opacity: 100%;
+}
+
+.started #start {
+    display: none
+}
+
+.started #stop {
+    display: block
+}
+
+.started #reset {
+    visibility: hidden
+}

docs/examples/tutorial/stopwatch.py

@@ -0,0 +1,105 @@
+from time import monotonic
+
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.reactive import Reactive
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+    start_time = Reactive(monotonic)
+    time = Reactive.init(0.0)
+    total = Reactive(0.0)
+
+    def on_mount(self) -> None:
+        """Event handler called when widget is added to the app."""
+        self.update_timer = self.set_interval(1 / 60, self.update_time, pause=True)
+
+    def update_time(self) -> None:
+        """Method to update time to current."""
+        self.time = self.total + (monotonic() - self.start_time)
+
+    def watch_time(self, time: float) -> None:
+        """Called when the time attribute changes."""
+        minutes, seconds = divmod(time, 60)
+        hours, minutes = divmod(minutes, 60)
+        self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}")
+
+    def start(self) -> None:
+        """Method to start (or resume) time updating."""
+        self.start_time = monotonic()
+        self.update_timer.resume()
+
+    def stop(self):
+        """Method to stop the time display updating."""
+        self.update_timer.pause()
+        self.total += monotonic() - self.start_time
+        self.time = self.total
+
+    def reset(self):
+        """Method to reset the time display to zero."""
+        self.total = 0
+        self.time = 0
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Event handler called when a button is pressed."""
+        button_id = event.button.id
+        time_display = self.query_one(TimeDisplay)
+        if button_id == "start":
+            time_display.start()
+            self.add_class("started")
+        elif button_id == "stop":
+            time_display.stop()
+            self.remove_class("started")
+        elif button_id == "reset":
+            time_display.reset()
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay()
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Called to add widgets to the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch(), id="timers")
+
+    def on_load(self) -> None:
+        """Called when the app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+        self.bind("a", "add_stopwatch", description="Add")
+        self.bind("r", "remove_stopwatch", description="Remove")
+
+    def action_add_stopwatch(self) -> None:
+        """An action to add a timer."""
+        new_stopwatch = Stopwatch()
+        self.query_one("#timers").mount(new_stopwatch)
+        new_stopwatch.scroll_visible()
+
+    def action_remove_stopwatch(self) -> None:
+        """Called to remove a timer."""
+        timers = self.query("Stopwatch")
+        if timers:
+            timers.last().remove()
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp(css_path="stopwatch.css")
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch01.py

@@ -0,0 +1,24 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        yield Footer()
+
+    def on_load(self) -> None:
+        """Called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp()
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch02.css

@@ -0,0 +1 @@
+/* Blank for now */

docs/examples/tutorial/stopwatch02.py

@@ -0,0 +1,41 @@
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay("00:00:00.00")
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch())
+
+    def on_load(self) -> None:
+        """Event handler called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp()
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch03.css

@@ -0,0 +1,30 @@
+Stopwatch {
+    layout: horizontal;
+    background: $panel-darken-1;
+    height: 5;
+    padding: 1;
+    margin: 1;
+}
+
+TimeDisplay {
+    content-align: center middle;
+    text-opacity: 60%;
+    height: 3;
+}
+
+Button {
+    width: 16;
+}
+
+#start {
+    dock: left;
+}
+
+#stop {
+    dock: left;
+    display: none;
+}
+
+#reset {
+    dock: right;
+}

docs/examples/tutorial/stopwatch03.py

@@ -0,0 +1,41 @@
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay("00:00:00.00")
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch())
+
+    def on_load(self) -> None:
+        """Called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp(css_path="stopwatch03.css")
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch04.css

@@ -0,0 +1,53 @@
+Stopwatch {
+    layout: horizontal;
+    background: $panel-darken-1;
+    height: 5;
+    min-width: 50;
+    margin: 1;
+    padding: 1;
+}
+
+TimeDisplay {
+    content-align: center middle;
+    text-opacity: 60%;
+    height: 3;
+}
+
+Button {
+    width: 16;
+}
+
+#start {
+    dock: left;
+}
+
+#stop {
+    dock: left;
+    display: none;
+}
+
+#reset {
+    dock: right;
+}
+
+.started {
+    text-style: bold;
+    background: $success;
+    color: $text-success;
+}
+
+.started TimeDisplay {
+    text-opacity: 100%;
+}
+
+.started #start {
+    display: none
+}
+
+.started #stop {
+    display: block
+}
+
+.started #reset {
+    visibility: hidden
+}

docs/examples/tutorial/stopwatch04.py

@@ -0,0 +1,48 @@
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Event handler called when a button is pressed."""
+        if event.button.id == "start":
+            self.add_class("started")
+        elif event.button.id == "stop":
+            self.remove_class("started")
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay("00:00:00.00")
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch())
+
+    def on_load(self) -> None:
+        """Called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp(css_path="stopwatch04.css")
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch05.py

@@ -0,0 +1,68 @@
+from time import monotonic
+
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.reactive import Reactive
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+    start_time = Reactive(monotonic)
+    time = Reactive.init(0.0)
+
+    def on_mount(self) -> None:
+        """Event handler called when widget is added to the app."""
+        self.set_interval(1 / 60, self.update_time)
+
+    def update_time(self) -> None:
+        """Method to update the time to the current time."""
+        self.time = monotonic() - self.start_time
+
+    def watch_time(self, time: float) -> None:
+        """Called when the time attribute changes."""
+        minutes, seconds = divmod(time, 60)
+        hours, minutes = divmod(minutes, 60)
+        self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}")
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Event handler called when a button is pressed."""
+        if event.button.id == "start":
+            self.add_class("started")
+        elif event.button.id == "stop":
+            self.remove_class("started")
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay()
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch())
+
+    def on_load(self) -> None:
+        """Event handler called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp(css_path="stopwatch04.css")
+if __name__ == "__main__":
+    app.run()

docs/examples/tutorial/stopwatch06.py

@@ -0,0 +1,91 @@
+from time import monotonic
+
+from textual.app import App, ComposeResult
+from textual.layout import Container
+from textual.reactive import Reactive
+from textual.widgets import Button, Header, Footer, Static
+
+
+class TimeDisplay(Static):
+    """A widget to display elapsed time."""
+
+    start_time = Reactive(monotonic)
+    time = Reactive.init(0.0)
+    total = Reactive(0.0)
+
+    def on_mount(self) -> None:
+        """Event handler called when widget is added to the app."""
+        self.update_timer = self.set_interval(1 / 60, self.update_time, pause=True)
+
+    def update_time(self) -> None:
+        """Method to update time to current."""
+        self.time = self.total + (monotonic() - self.start_time)
+
+    def watch_time(self, time: float) -> None:
+        """Called when the time attribute changes."""
+        minutes, seconds = divmod(time, 60)
+        hours, minutes = divmod(minutes, 60)
+        self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}")
+
+    def start(self) -> None:
+        """Method to start (or resume) time updating."""
+        self.start_time = monotonic()
+        self.update_timer.resume()
+
+    def stop(self):
+        """Method to stop the time display updating."""
+        self.update_timer.pause()
+        self.total += monotonic() - self.start_time
+        self.time = self.total
+
+    def reset(self):
+        """Method to reset the time display to zero."""
+        self.total = 0
+        self.time = 0
+
+
+class Stopwatch(Static):
+    """A stopwatch widget."""
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Event handler called when a button is pressed."""
+        button_id = event.button.id
+        time_display = self.query_one(TimeDisplay)
+        if button_id == "start":
+            time_display.start()
+            self.add_class("started")
+        elif button_id == "stop":
+            time_display.stop()
+            self.remove_class("started")
+        elif button_id == "reset":
+            time_display.reset()
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets of a stopwatch."""
+        yield Button("Start", id="start", variant="success")
+        yield Button("Stop", id="stop", variant="error")
+        yield Button("Reset", id="reset")
+        yield TimeDisplay()
+
+
+class StopwatchApp(App):
+    """A Textual app to manage stopwatches."""
+
+    def compose(self) -> ComposeResult:
+        """Called to add widgets to the app."""
+        yield Header()
+        yield Footer()
+        yield Container(Stopwatch(), Stopwatch(), Stopwatch())
+
+    def on_load(self) -> None:
+        """Event handler called when app first loads."""
+        self.bind("d", "toggle_dark", description="Dark mode")
+
+    def action_toggle_dark(self) -> None:
+        """An action to toggle dark mode."""
+        self.dark = not self.dark
+
+
+app = StopwatchApp(css_path="stopwatch04.css")
+if __name__ == "__main__":
+    app.run()