From a9100988b466833a9d4d7905ec6e714f78b25a17 Mon Sep 17 00:00:00 2001
From: Dave Pearson <davep@davep.org>
Date: Wed, 24 May 2023 21:36:14 +0100
Subject: [PATCH] Make a start on the SelectionList example apps

---
 docs/examples/widgets/selection_list.css      | 10 ++++
 docs/examples/widgets/selection_list.py       | 28 +++++++++++
 .../widgets/selection_list_selections.py      | 29 +++++++++++
 docs/widgets/selection_list.md                | 48 ++++++++++++++++++-
 4 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/widgets/selection_list.css
 create mode 100644 docs/examples/widgets/selection_list.py
 create mode 100644 docs/examples/widgets/selection_list_selections.py

diff --git a/docs/examples/widgets/selection_list.css b/docs/examples/widgets/selection_list.css
new file mode 100644
index 000000000..a05e16281
--- /dev/null
+++ b/docs/examples/widgets/selection_list.css
@@ -0,0 +1,10 @@
+Screen {
+    align: center middle;
+}
+
+SelectionList {
+    padding: 1;
+    border: solid $accent;
+    width: 80%;
+    height: 80%;
+}
diff --git a/docs/examples/widgets/selection_list.py b/docs/examples/widgets/selection_list.py
new file mode 100644
index 000000000..07b7d85bc
--- /dev/null
+++ b/docs/examples/widgets/selection_list.py
@@ -0,0 +1,28 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, SelectionList
+
+
+class SelectionListApp(App[None]):
+    CSS_PATH = "selection_list.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield SelectionList[int](
+            ("Falken's Maze", 0, True),
+            ("Black Jack", 1),
+            ("Gin Rummy", 2),
+            ("Hearts", 3),
+            ("Bridge", 4),
+            ("Checkers", 5),
+            ("Chess", 6, True),
+            ("Poker", 7),
+            ("Fighter Combat", 8, True),
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(SelectionList).border_title = "Shall we play some games?"
+
+
+if __name__ == "__main__":
+    SelectionListApp().run()
diff --git a/docs/examples/widgets/selection_list_selections.py b/docs/examples/widgets/selection_list_selections.py
new file mode 100644
index 000000000..d959a689f
--- /dev/null
+++ b/docs/examples/widgets/selection_list_selections.py
@@ -0,0 +1,29 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, SelectionList
+from textual.widgets.selection_list import Selection
+
+
+class SelectionListApp(App[None]):
+    CSS_PATH = "selection_list.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield SelectionList[int](
+            Selection("Falken's Maze", 0, True),
+            Selection("Black Jack", 1),
+            Selection("Gin Rummy", 2),
+            Selection("Hearts", 3),
+            Selection("Bridge", 4),
+            Selection("Checkers", 5),
+            Selection("Chess", 6, True),
+            Selection("Poker", 7),
+            Selection("Fighter Combat", 8, True),
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(SelectionList).border_title = "Shall we play some games?"
+
+
+if __name__ == "__main__":
+    SelectionListApp().run()
diff --git a/docs/widgets/selection_list.md b/docs/widgets/selection_list.md
index 6ef43a8a1..c7ac8df7a 100644
--- a/docs/widgets/selection_list.md
+++ b/docs/widgets/selection_list.md
@@ -9,7 +9,53 @@ A widget for showing a vertical list check boxes.
 
 ## Examples
 
-Some super-cool examples will appear here!
+A selection list is designed to be built up of single-line prompts (which
+can be Rich renderables) and an associated unique value.
+
+### Selections as tuples
+
+A selection list can be built with tuples, either of two or three values in
+length. Each tuple must contain a prompt and a value, and it can also
+optionally contain a flag for the initial selected state of the option.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/selection_list.py"}
+    ```
+
+=== "selection_list.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list.py"
+    ~~~
+
+=== "selection_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list.css"
+    ~~~
+
+### Selections as Selection objects
+
+Alternatively, selections can be passed in as
+[`Selection`][textual.widgets.selection_list.Selection]s:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/selection_list_selections.py"}
+    ```
+
+=== "selection_list_selections.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list_selections.py"
+    ~~~
+
+=== "selection_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/selection_list.css"
+    ~~~
 
 ## Reactive Attributes