From a821b2f8f69d66ede0be0e2748e3ef2385d275ab Mon Sep 17 00:00:00 2001
From: Dave Pearson <davep@davep.org>
Date: Thu, 23 Feb 2023 15:14:25 +0000
Subject: [PATCH] Add width reference documentation for radio buttons

A large part of the code to go with this is to show off a radio set; I feel
it makes sense to use the same code for both bits of documentation given
that a radio button only really makes sense inside a radio set.
---
 docs/examples/widgets/radio_set.css | 12 ++++++
 docs/examples/widgets/radio_set.py  | 43 +++++++++++++++++++++
 docs/widgets/radiobutton.md         | 59 +++++++++++++++++++++++++++++
 mkdocs-nav.yml                      |  1 +
 4 files changed, 115 insertions(+)
 create mode 100644 docs/examples/widgets/radio_set.css
 create mode 100644 docs/examples/widgets/radio_set.py
 create mode 100644 docs/widgets/radiobutton.md

diff --git a/docs/examples/widgets/radio_set.css b/docs/examples/widgets/radio_set.css
new file mode 100644
index 000000000..21238750a
--- /dev/null
+++ b/docs/examples/widgets/radio_set.css
@@ -0,0 +1,12 @@
+Screen {
+    align: center middle;
+}
+
+Horizontal {
+    align: center middle;
+    height: auto;
+}
+
+RadioSet {
+    width: 45%;
+}
diff --git a/docs/examples/widgets/radio_set.py b/docs/examples/widgets/radio_set.py
new file mode 100644
index 000000000..916c58293
--- /dev/null
+++ b/docs/examples/widgets/radio_set.py
@@ -0,0 +1,43 @@
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import RadioButton, RadioSet
+
+
+class RadioChoicesApp(App[None]):
+    CSS_PATH = "radio_set.css"
+
+    def compose(self) -> ComposeResult:
+        yield Horizontal(
+            RadioSet(
+                RadioButton("Battlestar Galactica"),
+                RadioButton("Dune 1984"),
+                RadioButton("Dune 2021"),
+                RadioButton("Serenity", value=True),
+                RadioButton("Star Trek: The Motion Picture"),
+                RadioButton("Star Wars: A New Hope"),
+                RadioButton("The Last Starfighter"),
+                RadioButton(
+                    "Total Recall :backhand_index_pointing_right: :red_circle:",
+                    id="focus_me",
+                ),
+                RadioButton("Wing Commander"),
+            ),
+            RadioSet(
+                "Amanda",
+                "Connor MacLeod",
+                "Duncan MacLeod",
+                "Heather MacLeod",
+                "Joe Dawson",
+                "Kurgan, [bold italic red]The[/]",
+                "Methos",
+                "Rachel Ellenstein",
+                "Ramírez",
+            ),
+        )
+
+    def on_mount(self) -> None:
+        self.query_one("#focus_me", RadioButton).focus()
+
+
+if __name__ == "__main__":
+    RadioChoicesApp().run()
diff --git a/docs/widgets/radiobutton.md b/docs/widgets/radiobutton.md
new file mode 100644
index 000000000..f03be2264
--- /dev/null
+++ b/docs/widgets/radiobutton.md
@@ -0,0 +1,59 @@
+# RadioButton
+
+A simple radio button which stores a boolean value.
+
+- [x] Focusable
+- [ ] Container
+
+## Example
+
+The example below shows radio buttons, used within [RadioSet][textual.widgets.RadioSet]s.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/radio_set.py"}
+    ```
+
+=== "radio_set.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/radio_set.py"
+    ```
+
+=== "radio_set.css"
+
+    ```sass
+    --8<-- "docs/examples/widgets/radio_set.css"
+    ```
+
+## Reactive Attributes
+
+| Name    | Type   | Default | Description                    |
+|---------|--------|---------|--------------------------------|
+| `value` | `bool` | `False` | The value of the radio button. |
+
+## Bindings
+
+The radio button widget defines directly the following bindings:
+
+::: textual.widgets._toggle_button.ToggleButton.BINDINGS
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+## Component Classes
+
+The radio button widget provides the following component classes:
+
+::: textual.widgets._toggle_button.ToggleButton.COMPONENT_CLASSES
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+## Messages
+
+### ::: textual.widgets.RadioButton.Changed
+
+## See Also
+
+- [RadioButton](../api/radiobutton.md) code reference
diff --git a/mkdocs-nav.yml b/mkdocs-nav.yml
index a47e58f59..c2a7f83ab 100644
--- a/mkdocs-nav.yml
+++ b/mkdocs-nav.yml
@@ -134,6 +134,7 @@ nav:
       - "widgets/markdown_viewer.md"
       - "widgets/markdown.md"
       - "widgets/placeholder.md"
+      - "widgets/radiobutton.md"
       - "widgets/static.md"
       - "widgets/switch.md"
       - "widgets/text_log.md"