Merge branch 'main' into messages-control

docs/examples/widgets/option_list_tables.py

@@ -4,7 +4,6 @@ from rich.table import Table
 
 from textual.app import App, ComposeResult
 from textual.widgets import Footer, Header, OptionList
-from textual.widgets.option_list import Option, Separator
 
 COLONIES: tuple[tuple[str, str, str, str], ...] = (
     ("Aerilon", "Demeter", "1.2 Billion", "Gaoth"),

docs/examples/widgets/select.css

@@ -0,0 +1,11 @@
+Screen {
+    align: center top;
+}
+
+Select {
+    width: 60;
+    margin: 2;
+}
+Input {
+    width: 60;
+}

docs/examples/widgets/select_widget.py

@@ -0,0 +1,26 @@
+from textual import on
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Select
+
+LINES = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.""".splitlines()
+
+
+class SelectApp(App):
+    CSS_PATH = "select.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Select((line, line) for line in LINES)
+
+    @on(Select.Changed)
+    def select_changed(self, event: Select.Changed) -> None:
+        self.title = str(event.value)
+
+
+if __name__ == "__main__":
+    app = SelectApp()
+    app.run()

docs/widget_gallery.md

@@ -188,6 +188,16 @@ A collection of radio buttons, that enforces uniqueness.
 ```{.textual path="docs/examples/widgets/radio_set.py"}
 ```
 
+## Select
+
+Select from a number of possible options.
+
+[Select reference](./widgets/select.md){ .md-button .md-button--primary }
+
+```{.textual path="docs/examples/widgets/select_widget.py" press="tab,enter,down,down"}
+```
+
+
 ## Static
 
 Displays simple static content. Typically used as a base class.

docs/widgets/select.md

@@ -0,0 +1,90 @@
+# Select
+
+!!! tip "Added in version 0.24.0"
+
+A Select widget is a compact control to allow the user to select between a number of possible options.
+
+
+- [X] Focusable
+- [ ] Container
+
+
+The options in a select control may be passed in to the constructor or set later with [set_options][textual.widgets.Select.set_options].
+Options should be given as a sequence of tuples consisting of two values: the first is the string (or [Rich Renderable](https://rich.readthedocs.io/en/latest/protocol.html)) to display in the control and list of options, the second is the value of option.
+
+The value of the currently selected option is stored in the `value` attribute of the widget, and the `value` attribute of the [Changed][textual.widgets.Select.Changed] message.
+
+
+## Typing
+
+The `Select` control is a typing Generic which allows you to set the type of the option values.
+For instance, if the data type for your values is an integer, you would type the widget as follows:
+
+```python
+options = [("First", 1), ("Second", 2)]
+my_select: Select[int] =  Select(options)
+```
+
+!!! note
+
+    Typing is entirely optional.
+
+    If you aren't familiar with typing or don't want to worry about it right now, feel free to ignore it.
+
+## Example
+
+The following example presents a `Select` with a number of options.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/select_widget.py"}
+    ```
+
+=== "Output (expanded)"
+
+    ```{.textual path="docs/examples/widgets/select_widget.py" press="tab,enter,down,down"}
+    ```
+
+
+=== "select_widget.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/select_widget.py"
+    ```
+
+=== "select.css"
+
+    ```sass
+    --8<-- "docs/examples/widgets/select.css"
+    ```
+
+## Messages
+
+-  [Select.Changed][textual.widgets.Select.Changed]
+
+
+## Reactive attributes
+
+
+| Name       | Type                 | Default | Description                         |
+| ---------- | -------------------- | ------- | ----------------------------------- |
+| `expanded` | `bool`               | `False` | True to expand the options overlay. |
+| `value`    | `SelectType \| None` | `None`  | Current value of the Select.        |
+
+
+## Bindings
+
+The Select widget defines the following bindings:
+
+::: textual.widgets.Select.BINDINGS
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+
+---
+
+
+::: textual.widgets.Select
+    options:
+      heading_level: 2