List view

docs/api/list_item.md

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

docs/api/list_view.md

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

docs/examples/widgets/list_view.css

@@ -0,0 +1,13 @@
+Screen {
+    align: center middle;
+}
+
+ListView {
+    width: 30;
+    height: auto;
+    margin: 2 2;
+}
+
+Label {
+    padding: 1 2;
+}

docs/examples/widgets/list_view.py

@@ -0,0 +1,17 @@
+from textual.app import App, ComposeResult
+from textual.widgets import ListView, ListItem, Label, Footer
+
+
+class ListViewExample(App):
+    def compose(self) -> ComposeResult:
+        yield ListView(
+            ListItem(Label("One")),
+            ListItem(Label("Two")),
+            ListItem(Label("Three")),
+        )
+        yield Footer()
+
+
+app = ListViewExample(css_path="list_view.css")
+if __name__ == "__main__":
+    app.run()

docs/widgets/list_item.md

@@ -0,0 +1,40 @@
+# List Item
+
+`ListItem` is the type of the elements in a `ListView`.
+
+- [] Focusable
+- [] Container
+
+## Example
+
+The example below shows an app with a simple `ListView`, consisting
+of multiple `ListItem`s. The arrow keys can be used to navigate the list.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/list_view.py"}
+    ```
+
+=== "list_view.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/list_view.py"
+    ```
+
+## Reactive Attributes
+
+| Name          | Type   | Default | Description                          |
+|---------------|--------|---------|--------------------------------------|
+| `highlighted` | `bool` | `False` | True if this ListItem is highlighted |
+
+## Messages
+
+#### Attributes
+
+| attribute | type       | purpose                     |
+|-----------|------------|-----------------------------|
+| `item`    | `ListItem` | The item that was selected. |
+
+## See Also
+
+* [ListItem](../api/list_item.md) code reference

docs/widgets/list_view.md

@@ -0,0 +1,78 @@
+# List View
+
+Displays a vertical list of `ListItem`s which can be highlighted and selected.
+Supports keyboard navigation.
+
+- [x] Focusable
+- [x] Container
+
+## Example
+
+The example below shows an app with a simple `ListView`.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/list_view.py"}
+    ```
+
+=== "list_view.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/list_view.py"
+    ```
+
+## Reactive Attributes
+
+| Name    | Type  | Default | Description                     |
+|---------|-------|---------|---------------------------------|
+| `index` | `int` | `0`     | The currently highlighted index |
+
+## Messages
+
+### Highlighted
+
+The `ListView.Highlighted` message is emitted when the highlight changes.
+This happens when you use the arrow keys on your keyboard and when you
+click on a list item.
+
+- [x] Bubbles
+
+#### Attributes
+
+| attribute | type       | purpose                        |
+|-----------|------------|--------------------------------|
+| `item`    | `ListItem` | The item that was highlighted. |
+
+### Selected
+
+The `ListView.Selected` message is emitted when a list item is selected.
+You can select a list item by pressing ++enter++ while it is highlighted,
+or by clicking on it.
+
+- [x] Bubbles
+
+#### Attributes
+
+| attribute | type       | purpose                     |
+|-----------|------------|-----------------------------|
+| `item`    | `ListItem` | The item that was selected. |
+
+
+### ChildrenUpdated
+
+The `ListView.ChildrenUpdated` message is emitted when the elements in the `ListView`
+are changed (e.g. a child is added, or the list is cleared)
+
+- [x] Bubbles
+
+#### Attributes
+
+| attribute  | type             | purpose                   |
+|------------|------------------|---------------------------|
+| `children` | `list[ListItem]` | The new ListView children |
+
+
+
+## See Also
+
+* [ListView](../api/list_view.md) code reference

mkdocs.yml

@@ -97,6 +97,8 @@ nav:
       - "widgets/header.md"
       - "widgets/input.md"
       - "widgets/label.md"
+      - "widgets/list_view.md"
+      - "widgets/list_item.md"
       - "widgets/static.md"
       - "widgets/tree_control.md"
   - API:
@@ -111,6 +113,8 @@ nav:
     - "api/geometry.md"
     - "api/header.md"
     - "api/label.md"
+    - "api/list_view.md"
+    - "api/list_item.md"
     - "api/message_pump.md"
     - "api/message.md"
     - "api/pilot.md"

src/textual/app.py

@@ -1918,24 +1918,6 @@ def _detach_from_dom(self, widgets: list[Widget]) -> list[Widget]:
         # prune event.
         return pruned_remove
 
-    async def _on_prune(self, event: events.Prune) -> None:
-        """Handle a prune event.
-
-        Args:
-            event (events.Prune): The prune event.
-        """
-
-        try:
-            # Prune all the widgets.
-            for widget in event.widgets:
-                await self._prune_node(widget)
-        finally:
-            # Finally, flag that we're done.
-            event.finished_flag.set()
-
-        # Flag that the layout needs refreshing.
-        self.refresh(layout=True)
-
     def _walk_children(self, root: Widget) -> Iterable[list[Widget]]:
         """Walk children depth first, generating widgets and a list of their siblings.
 

src/textual/dom.py

@@ -259,7 +259,7 @@ def screen(self) -> "Screen":
         from .screen import Screen
 
         node = self
-        while node and not isinstance(node, Screen):
+        while node is not None and not isinstance(node, Screen):
             node = node._parent
         if not isinstance(node, Screen):
             raise NoScreen("node has no screen")

src/textual/widgets/__init__.py

@@ -16,8 +16,10 @@
     from ._footer import Footer
     from ._header import Header
     from ._label import Label
-    from ._placeholder import Placeholder
+    from ._list_view import ListView
+    from ._list_item import ListItem
     from ._pretty import Pretty
+    from ._placeholder import Placeholder
     from ._static import Static
     from ._input import Input
     from ._text_log import TextLog
@@ -31,6 +33,8 @@
     "DirectoryTree",
     "Footer",
     "Header",
+    "ListItem",
+    "ListView",
     "Label",
     "Placeholder",
     "Pretty",

src/textual/widgets/__init__.pyi

@@ -6,6 +6,8 @@ from ._directory_tree import DirectoryTree as DirectoryTree
 from ._footer import Footer as Footer
 from ._header import Header as Header
 from ._label import Label as Label
+from ._list_view import ListView as ListView
+from ._list_item import ListItem as ListItem
 from ._placeholder import Placeholder as Placeholder
 from ._pretty import Pretty as Pretty
 from ._static import Static as Static

src/textual/widgets/_list_item.py

@@ -0,0 +1,39 @@
+from textual import events
+from textual.message import Message
+from textual.reactive import reactive
+from textual.widget import Widget
+
+
+class ListItem(Widget, can_focus=False):
+    DEFAULT_CSS = """
+    ListItem {
+        color: $text;
+        height: auto;
+        background: $panel-lighten-1;
+        overflow: hidden hidden;
+    }
+    ListItem > Widget :hover {
+        background: $boost;
+    }
+    ListView ListItem.--highlight {
+        background: $accent 50%;
+    }
+    ListView:focus ListItem.--highlight {
+        background: $accent;
+    }
+    ListItem > Widget {
+        height: auto;
+    }
+    """
+    highlighted = reactive(False)
+
+    def on_click(self, event: events.Click) -> None:
+        self.emit_no_wait(self._ChildClicked(self))
+
+    def watch_highlighted(self, value: bool) -> None:
+        self.set_class(value, "--highlight")
+
+    class _ChildClicked(Message):
+        """For informing with the parent ListView that we were clicked"""
+
+        pass