1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# SelectionList
!!! tip "Added in version 0.27.0"
A widget for showing a vertical list of selectable options.
- [x] Focusable
- [ ] Container
## Typing
The `SelectionList` control is a
[`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic),
which allows you to set the type of the
[selection values][textual.widgets.selection_list.Selection.value]. For instance, if
the data type for your values is an integer, you would type the widget as
follows:
```python
selections = [("First", 1), ("Second", 2)]
my_selection_list: SelectionList[int] = SelectionList(*selections)
```
!!! 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.
## Examples
A selection list is designed to be built up of single-line prompts (which
can be [Rich `Text`](https://rich.readthedocs.io/en/stable/text.html)) 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_tuples.py"}
```
=== "selection_list_tuples.py"
~~~python
--8<-- "docs/examples/widgets/selection_list_tuples.py"
~~~
1. Note that the `SelectionList` is typed as `int`, for the type of the values.
=== "selection_list.tcss"
~~~css
--8<-- "docs/examples/widgets/selection_list.tcss"
~~~
### 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"
~~~
1. Note that the `SelectionList` is typed as `int`, for the type of the values.
=== "selection_list.tcss"
~~~css
--8<-- "docs/examples/widgets/selection_list.tcss"
~~~
### 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` 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 values.
=== "selection_list.tcss"
~~~css
--8<-- "docs/examples/widgets/selection_list_selected.tcss"
~~~
## Reactive Attributes
| Name | Type | Default | Description |
|---------------|-----------------|---------|------------------------------------------------------------------------------|
| `highlighted` | `int` \| `None` | `None` | The index of the highlighted selection. `None` means nothing is highlighted. |
## Messages
- [SelectionList.SelectionHighlighted][textual.widgets.SelectionList.SelectionHighlighted]
- [SelectionList.SelectionToggled][textual.widgets.SelectionList.SelectionToggled]
- [SelectionList.SelectedChanged][textual.widgets.SelectionList.SelectedChanged]
## Bindings
The selection list widget defines the following bindings:
::: textual.widgets.SelectionList.BINDINGS
options:
show_root_heading: false
show_root_toc_entry: false
It inherits from [`OptionList`][textual.widgets.OptionList]
and so also inherits the following bindings:
::: textual.widgets.OptionList.BINDINGS
options:
show_root_heading: false
show_root_toc_entry: false
## Component Classes
The selection list provides the following component classes:
::: textual.widgets.SelectionList.COMPONENT_CLASSES
options:
show_root_heading: false
show_root_toc_entry: false
It inherits from [`OptionList`][textual.widgets.OptionList] and so also
makes use of the following component classes:
::: textual.widgets.OptionList.COMPONENT_CLASSES
options:
show_root_heading: false
show_root_toc_entry: false
::: textual.widgets.SelectionList
options:
heading_level: 2
::: textual.widgets.selection_list
options:
heading_level: 2
|
