From fb4f804dff007e6d1cd586e9042d6b9f8837b173 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?= <5621605+rodrigogiraoserrao@users.noreply.github.com> Date: Thu, 26 Jan 2023 11:53:37 +0000 Subject: [PATCH] Improve widget message docstrings. --- src/textual/widgets/__init__.py | 2 +- src/textual/widgets/_button.py | 3 ++ src/textual/widgets/_checkbox.py | 5 +- src/textual/widgets/_directory_tree.py | 11 ++++- src/textual/widgets/_input.py | 12 +++-- src/textual/widgets/_list_view.py | 51 +++++++++++--------- src/textual/widgets/_tree.py | 64 +++++++++++++++----------- 7 files changed, 94 insertions(+), 54 deletions(-) diff --git a/src/textual/widgets/__init__.py b/src/textual/widgets/__init__.py index 4628cbe92..f26679d33 100644 --- a/src/textual/widgets/__init__.py +++ b/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: diff --git a/src/textual/widgets/_button.py b/src/textual/widgets/_button.py index 81b54783f..164ca38ef 100644 --- a/src/textual/widgets/_button.py +++ b/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. """ diff --git a/src/textual/widgets/_checkbox.py b/src/textual/widgets/_checkbox.py index 428b27a1e..305858faf 100644 --- a/src/textual/widgets/_checkbox.py +++ b/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. diff --git a/src/textual/widgets/_directory_tree.py b/src/textual/widgets/_directory_tree.py index 9d6cbdc83..0be163d67 100644 --- a/src/textual/widgets/_directory_tree.py +++ b/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__( diff --git a/src/textual/widgets/_input.py b/src/textual/widgets/_input.py index 2015f7277..912fe67f2 100644 --- a/src/textual/widgets/_input.py +++ b/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. """ diff --git a/src/textual/widgets/_list_view.py b/src/textual/widgets/_list_view.py index f05622616..87675ec47 100644 --- a/src/textual/widgets/_list_view.py +++ b/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 diff --git a/src/textual/widgets/_tree.py b/src/textual/widgets/_tree.py index 54cdda39c..bcd8c0aa7 100644 --- a/src/textual/widgets/_tree.py +++ b/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,