From 623b70d4ac8983ac104b27062abab3cb2bbdbdfa Mon Sep 17 00:00:00 2001
From: Dave Pearson <davep@davep.org>
Date: Mon, 6 Mar 2023 10:53:12 +0000
Subject: [PATCH] Add an example of using a RadioSet.Changed message (#1935)

Unlike a few other widgets, the RadioSet is pretty much all about reacting
to the selection result; the question of how you go about it has already
come up and while the message is documented, complete with all properties,
it can't hurt to have an illustrative example of code that uses it.

Here I add an extra RadioSet example that sits with the message in the
reference. This should help the reader better follow how to use it, and also
gives something to link to if someone hasn't got that far into the
documentation yet but is attempting to use the RadioSet.
---
 docs/examples/widgets/radio_set_changed.css | 12 ++++++
 docs/examples/widgets/radio_set_changed.py  | 43 +++++++++++++++++++++
 docs/widgets/radioset.md                    | 19 +++++++++
 3 files changed, 74 insertions(+)
 create mode 100644 docs/examples/widgets/radio_set_changed.css
 create mode 100644 docs/examples/widgets/radio_set_changed.py

diff --git a/docs/examples/widgets/radio_set_changed.css b/docs/examples/widgets/radio_set_changed.css
new file mode 100644
index 000000000..47583c1d8
--- /dev/null
+++ b/docs/examples/widgets/radio_set_changed.css
@@ -0,0 +1,12 @@
+Vertical {
+    align: center middle;
+}
+
+Horizontal {
+    align: center middle;
+    height: auto;
+}
+
+RadioSet {
+    width: 45%;
+}
diff --git a/docs/examples/widgets/radio_set_changed.py b/docs/examples/widgets/radio_set_changed.py
new file mode 100644
index 000000000..be0ecbab2
--- /dev/null
+++ b/docs/examples/widgets/radio_set_changed.py
@@ -0,0 +1,43 @@
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Label, RadioButton, RadioSet
+
+
+class RadioSetChangedApp(App[None]):
+    CSS_PATH = "radio_set_changed.css"
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            with Horizontal():
+                with RadioSet():
+                    yield RadioButton("Battlestar Galactica")
+                    yield RadioButton("Dune 1984")
+                    yield RadioButton("Dune 2021")
+                    yield RadioButton("Serenity", value=True)
+                    yield RadioButton("Star Trek: The Motion Picture")
+                    yield RadioButton("Star Wars: A New Hope")
+                    yield RadioButton("The Last Starfighter")
+                    yield RadioButton(
+                        "Total Recall :backhand_index_pointing_right: :red_circle:",
+                        id="focus_me",
+                    )
+                    yield RadioButton("Wing Commander")
+            with Horizontal():
+                yield Label(id="pressed")
+            with Horizontal():
+                yield Label(id="index")
+
+    def on_mount(self) -> None:
+        self.query_one("#focus_me", RadioButton).focus()
+
+    def on_radio_set_changed(self, event: RadioSet.Changed) -> None:
+        self.query_one("#pressed", Label).update(
+            f"Pressed button label: {event.pressed.label}"
+        )
+        self.query_one("#index", Label).update(
+            f"Pressed button index: {event.input.pressed_index}"
+        )
+
+
+if __name__ == "__main__":
+    RadioSetChangedApp().run()
diff --git a/docs/widgets/radioset.md b/docs/widgets/radioset.md
index 7b1cc27dc..41e1cf2d2 100644
--- a/docs/widgets/radioset.md
+++ b/docs/widgets/radioset.md
@@ -31,6 +31,25 @@ The example below shows two radio sets, one built using a collection of
 
 ### ::: textual.widgets.RadioSet.Changed
 
+Here is an example of using the message to react to changes in a `RadioSet`:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/radio_set_changed.py" press="enter"}
+    ```
+
+=== "radio_set_changed.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/radio_set_changed.py"
+    ```
+
+=== "radio_set_changed.css"
+
+    ```sass
+    --8<-- "docs/examples/widgets/radio_set_changed.css"
+    ```
+
 ## See Also
 
 - [RadioSet](../api/radioset.md) code reference