On decorator (#2453)

* Add on decorator

* decorator code

* docs for on decorator

* Examples

* test errors

* simplify listing

* words

* changelog

* Update docs/guide/events.md

Co-authored-by: Dave Pearson <davep@davep.org>

* Update docs/guide/events.md

Co-authored-by: Dave Pearson <davep@davep.org>

* Update docs/examples/events/on_decorator.css

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Update docs/guide/events.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* rewording

* comment

* clarification

* Added note

---------

Co-authored-by: Dave Pearson <davep@davep.org>
Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

docs/examples/events/custom01.py

@@ -1,6 +1,6 @@
 from textual.app import App, ComposeResult
 from textual.color import Color
-from textual.message import Message, MessageTarget
+from textual.message import Message
 from textual.widgets import Static
 
 

docs/examples/events/on_decorator.css

@@ -0,0 +1,8 @@
+Screen {
+    align: center middle;
+    layout: horizontal;
+}
+
+Button {
+    margin: 2 4;
+}

docs/examples/events/on_decorator01.py

@@ -0,0 +1,27 @@
+from textual import on
+from textual.app import App, ComposeResult
+from textual.widgets import Button
+
+
+class OnDecoratorApp(App):
+    CSS_PATH = "on_decorator.css"
+
+    def compose(self) -> ComposeResult:
+        """Three buttons."""
+        yield Button("Bell", id="bell")
+        yield Button("Toggle dark", classes="toggle dark")
+        yield Button("Quit", id="quit")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle all button pressed events."""
+        if event.button.id == "bell":
+            self.bell()
+        elif event.button.has_class("toggle", "dark"):
+            self.dark = not self.dark
+        elif event.button.id == "quit":
+            self.exit()
+
+
+if __name__ == "__main__":
+    app = OnDecoratorApp()
+    app.run()

docs/examples/events/on_decorator02.py

@@ -0,0 +1,33 @@
+from textual import on
+from textual.app import App, ComposeResult
+from textual.widgets import Button
+
+
+class OnDecoratorApp(App):
+    CSS_PATH = "on_decorator.css"
+
+    def compose(self) -> ComposeResult:
+        """Three buttons."""
+        yield Button("Bell", id="bell")
+        yield Button("Toggle dark", classes="toggle dark")
+        yield Button("Quit", id="quit")
+
+    @on(Button.Pressed, "#bell")  # (1)!
+    def play_bell(self):
+        """Called when the bell button is pressed."""
+        self.bell()
+
+    @on(Button.Pressed, ".toggle.dark")  # (2)!
+    def toggle_dark(self):
+        """Called when the 'toggle dark' button is pressed."""
+        self.dark = not self.dark
+
+    @on(Button.Pressed, "#quit")  # (3)!
+    def quit(self):
+        """Called when the quit button is pressed."""
+        self.exit()
+
+
+if __name__ == "__main__":
+    app = OnDecoratorApp()
+    app.run()