From 02c4f4d69bbff863cdeaa0880617b5e72a2e209f Mon Sep 17 00:00:00 2001
From: Dave Pearson <davep@davep.org>
Date: Thu, 25 May 2023 09:35:37 +0100
Subject: [PATCH] Add an example of using SelectionList.SelectedChanged

---
 .../widgets/selection_list_selected.css       | 19 +++++++++
 .../widgets/selection_list_selected.py        | 40 +++++++++++++++++++
 docs/widgets/selection_list.md                | 27 +++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 docs/examples/widgets/selection_list_selected.css
 create mode 100644 docs/examples/widgets/selection_list_selected.py

diff --git a/docs/examples/widgets/selection_list_selected.css b/docs/examples/widgets/selection_list_selected.css
new file mode 100644
index 000000000..92db41c14
--- /dev/null
+++ b/docs/examples/widgets/selection_list_selected.css
@@ -0,0 +1,19 @@
+Screen {
+    align: center middle;
+}
+
+Horizontal {
+    width: 80%;
+    height: 80%;
+}
+
+SelectionList {
+    padding: 1;
+    border: solid $accent;
+    width: 1fr;
+}
+
+Pretty {
+    width: 1fr;
+    border: solid $accent;
+}
diff --git a/docs/examples/widgets/selection_list_selected.py b/docs/examples/widgets/selection_list_selected.py
new file mode 100644
index 000000000..954fb36b1
--- /dev/null
+++ b/docs/examples/widgets/selection_list_selected.py
@@ -0,0 +1,40 @@
+from textual import on
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.events import Mount
+from textual.widgets import Footer, Header, Pretty, SelectionList
+from textual.widgets.selection_list import Selection
+
+
+class SelectionListApp(App[None]):
+    CSS_PATH = "selection_list_selected.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal():
+            yield SelectionList[str](  # (1)!
+                Selection("Falken's Maze", "secret_back_door", True),
+                Selection("Black Jack", "black_jack"),
+                Selection("Gin Rummy", "gin_rummy"),
+                Selection("Hearts", "hearts"),
+                Selection("Bridge", "bridge"),
+                Selection("Checkers", "checkers"),
+                Selection("Chess", "a_nice_game_of_chess", True),
+                Selection("Poker", "poker"),
+                Selection("Fighter Combat", "fighter_combat", True),
+            )
+            yield Pretty([])
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(SelectionList).border_title = "Shall we play some games?"
+        self.query_one(Pretty).border_title = "Selected games"
+
+    @on(Mount)
+    @on(SelectionList.SelectedChanged)
+    def update_selected_view(self) -> None:
+        self.query_one(Pretty).update(self.query_one(SelectionList).selected)
+
+
+if __name__ == "__main__":
+    SelectionListApp().run()
diff --git a/docs/widgets/selection_list.md b/docs/widgets/selection_list.md
index 498d886fb..9febaf88b 100644
--- a/docs/widgets/selection_list.md
+++ b/docs/widgets/selection_list.md
@@ -82,6 +82,33 @@ Alternatively, selections can be passed in as
     --8<-- "docs/examples/widgets/selection_list.css"
     ~~~
 
+### Handling changes to the selections
+
+Most of the time, when using the `SelectionList`, you will want to know when
+the collection of selected items has changed, this is ideally done using the
+[`SelectedChanged`][textual.widgets.SelectionList.SelectedChanged] message.
+Here is an example of using that message to update a
+[`Pretty`][textual.widgets.Pretty] with the collection of selected values:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/selection_list_selected.py"}
+    ```
+
+=== "selection_list_selections.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list_selected.py"
+    ~~~
+
+    1. Note that the `SelectionList` is typed as `str`, for the type of the vlaues.
+
+=== "selection_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list_selected.css"
+    ~~~
+
 ## Reactive Attributes
 
 | Name          | Type            | Default | Description                                                                  |