Improve widget message docstrings.

src/textual/widgets/__init__.py

@@ -4,7 +4,7 @@ import typing
 
 from ..case import camel_to_snake
 
-# ⚠️For any new built-in Widget we create, not only do we have to import them here and add them to `__all__`,
+# For any new built-in Widget we create, not only do we have to import them here and add them to `__all__`,
 # but also to the `__init__.pyi` file in this same folder - otherwise text editors and type checkers won't
 # be able to "see" them.
 if typing.TYPE_CHECKING:

src/textual/widgets/_button.py

@@ -162,6 +162,9 @@ class Button(Static, can_focus=True):
     class Pressed(Message, bubble=True):
         """Event sent when a `Button` is pressed.
 
+        Can be handled using `on_button_pressed` in a subclass of `Button` or
+        in a parent widget in the DOM.
+
         Attributes:
             button: The button that was pressed.
         """

src/textual/widgets/_checkbox.py

@@ -77,7 +77,10 @@ class Checkbox(Widget, can_focus=True):
     """The position of the slider."""
 
     class Changed(Message, bubble=True):
-        """Checkbox was toggled.
+        """Emitted when the status of the checkbox changes.
+
+        Can be handled using `on_checkbox_changed` in a subclass of `Checkbox`
+        or in a parent widget in the DOM.
 
         Attributes:
             value: The value that the checkbox was changed to.

src/textual/widgets/_directory_tree.py

@@ -67,8 +67,17 @@ class DirectoryTree(Tree[DirEntry]):
     """
 
     class FileSelected(Message, bubble=True):
+        """Emitted when a file is selected.
+
+        Can be handled using `on_directory_tree_file_selected` in a subclass of
+        `DirectoryTree` or in a parent widget in the DOM.
+
+        Attributes:
+            path: The path of the file that was selected.
+        """
+
         def __init__(self, sender: MessageTarget, path: str) -> None:
-            self.path = path
+            self.path: str = path
             super().__init__(sender)
 
     def __init__(

src/textual/widgets/_input.py

@@ -122,7 +122,10 @@ class Input(Widget, can_focus=True):
     max_size: reactive[int | None] = reactive(None)
 
     class Changed(Message, bubble=True):
-        """Value was changed.
+        """Emitted when the value changes.
+
+        Can be handled using `on_input_changed` in a subclass of `Input` or in a parent
+        widget in the DOM.
 
         Attributes:
             value: The value that the input was changed to.
@@ -135,10 +138,13 @@ class Input(Widget, can_focus=True):
             self.input: Input = sender
 
     class Submitted(Message, bubble=True):
-        """Sent when the enter key is pressed within an `Input`.
+        """Emitted when the enter key is pressed within an `Input`.
+
+        Can be handled using `on_input_submitted` in a subclass of `Input` or in a
+        parent widget in the DOM.
 
         Attributes:
-            value: The value of the `Input` being submitted..
+            value: The value of the `Input` being submitted.
             input: The `Input` widget that is being submitted.
         """
 

src/textual/widgets/_list_view.py

@@ -35,6 +35,35 @@ class ListView(Vertical, can_focus=True, can_focus_children=False):
 
     index = reactive(0, always_update=True)
 
+    class Highlighted(Message, bubble=True):
+        """Emitted when the highlighted item changes.
+
+        Highlighted item is controlled using up/down keys.
+        Can be handled using `on_list_view_highlighted` in a subclass of `ListView`
+        or in a parent widget in the DOM.
+
+        Attributes:
+            item: The highlighted item, if there is one highlighted.
+        """
+
+        def __init__(self, sender: ListView, item: ListItem | None) -> None:
+            super().__init__(sender)
+            self.item: ListItem | None = item
+
+    class Selected(Message, bubble=True):
+        """Emitted when a list item is selected, e.g. when you press the enter key on it.
+
+        Can be handled using `on_list_view_selected` in a subclass of `ListView` or in
+        a parent widget in the DOM.
+
+        Attributes:
+            item: The selected item.
+        """
+
+        def __init__(self, sender: ListView, item: ListItem) -> None:
+            super().__init__(sender)
+            self.item: ListItem = item
+
     def __init__(
         self,
         *children: ListItem,
@@ -147,25 +176,3 @@ class ListView(Vertical, can_focus=True, can_focus_children=False):
 
     def __len__(self):
         return len(self.children)
-
-    class Highlighted(Message, bubble=True):
-        """Emitted when the highlighted item changes. Highlighted item is controlled using up/down keys.
-
-        Attributes:
-            item: The highlighted item, if there is one highlighted.
-        """
-
-        def __init__(self, sender: ListView, item: ListItem | None) -> None:
-            super().__init__(sender)
-            self.item: ListItem | None = item
-
-    class Selected(Message, bubble=True):
-        """Emitted when a list item is selected, e.g. when you press the enter key on it
-
-        Attributes:
-            item: The selected item.
-        """
-
-        def __init__(self, sender: ListView, item: ListItem) -> None:
-            super().__init__(sender)
-            self.item: ListItem = item

src/textual/widgets/_tree.py

@@ -348,35 +348,12 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
         ),
     }
 
-    class NodeSelected(Generic[EventTreeDataType], Message, bubble=True):
-        """Event sent when a node is selected.
-
-        Attributes:
-            node: The node that was selected.
-        """
-
-        def __init__(
-            self, sender: MessageTarget, node: TreeNode[EventTreeDataType]
-        ) -> None:
-            self.node: TreeNode[EventTreeDataType] = node
-            super().__init__(sender)
-
-    class NodeExpanded(Generic[EventTreeDataType], Message, bubble=True):
-        """Event sent when a node is expanded.
-
-        Attributes:
-            node: The node that was expanded.
-        """
-
-        def __init__(
-            self, sender: MessageTarget, node: TreeNode[EventTreeDataType]
-        ) -> None:
-            self.node: TreeNode[EventTreeDataType] = node
-            super().__init__(sender)
-
     class NodeCollapsed(Generic[EventTreeDataType], Message, bubble=True):
         """Event sent when a node is collapsed.
 
+        Can be handled using `on_tree_node_collapsed` in a subclass of `Tree` or in a
+        parent node in the DOM.
+
         Attributes:
             node: The node that was collapsed.
         """
@@ -387,9 +364,28 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
             self.node: TreeNode[EventTreeDataType] = node
             super().__init__(sender)
 
+    class NodeExpanded(Generic[EventTreeDataType], Message, bubble=True):
+        """Event sent when a node is expanded.
+
+        Can be handled using `on_tree_node_expanded` in a subclass of `Tree` or in a
+        parent node in the DOM.
+
+        Attributes:
+            node: The node that was expanded.
+        """
+
+        def __init__(
+            self, sender: MessageTarget, node: TreeNode[EventTreeDataType]
+        ) -> None:
+            self.node: TreeNode[EventTreeDataType] = node
+            super().__init__(sender)
+
     class NodeHighlighted(Generic[EventTreeDataType], Message, bubble=True):
         """Event sent when a node is highlighted.
 
+        Can be handled using `on_tree_node_highlighted` in a subclass of `Tree` or in a
+        parent node in the DOM.
+
         Attributes:
             node: The node that was highlighted.
         """
@@ -400,6 +396,22 @@ class Tree(Generic[TreeDataType], ScrollView, can_focus=True):
             self.node: TreeNode[EventTreeDataType] = node
             super().__init__(sender)
 
+    class NodeSelected(Generic[EventTreeDataType], Message, bubble=True):
+        """Event sent when a node is selected.
+
+        Can be handled using `on_tree_node_selected` in a subclass of `Tree` or in a
+        parent node in the DOM.
+
+        Attributes:
+            node: The node that was selected.
+        """
+
+        def __init__(
+            self, sender: MessageTarget, node: TreeNode[EventTreeDataType]
+        ) -> None:
+            self.node: TreeNode[EventTreeDataType] = node
+            super().__init__(sender)
+
     def __init__(
         self,
         label: TextType,