SelectionList¶
Added in version 0.27.0
A widget for showing a vertical list of selectable options.
- Focusable
- Container
Typing¶
The SelectionList
control is a
Generic
,
which allows you to set the type of the
selection values. For instance, if
the data type for your values is an integer, you would type the widget as
follows:
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 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.
from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, SelectionList
class SelectionListApp(App[None]):
CSS_PATH = "selection_list.tcss"
def compose(self) -> ComposeResult:
yield Header()
yield SelectionList[int]( # (1)!
("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()
- Note that the
SelectionList
is typed asint
, for the type of the values.
Selections as Selection objects¶
Alternatively, selections can be passed in as
Selection
s:
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.tcss"
def compose(self) -> ComposeResult:
yield Header()
yield SelectionList[int]( # (1)!
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()
- Note that the
SelectionList
is typed asint
, for the type of the values.
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
message.
Here is an example of using that message to update a Pretty
with the
collection of selected values:
from textual import on
from textual.app import App, ComposeResult
from textual.containers import Horizontal
from textual.events import Mount
from textual.widgets import Footer, Header, Pretty, SelectionList
from textual.widgets.selection_list import Selection
class SelectionListApp(App[None]):
CSS_PATH = "selection_list_selected.tcss"
def compose(self) -> ComposeResult:
yield Header()
with Horizontal():
yield SelectionList[str]( # (1)!
Selection("Falken's Maze", "secret_back_door", True),
Selection("Black Jack", "black_jack"),
Selection("Gin Rummy", "gin_rummy"),
Selection("Hearts", "hearts"),
Selection("Bridge", "bridge"),
Selection("Checkers", "checkers"),
Selection("Chess", "a_nice_game_of_chess", True),
Selection("Poker", "poker"),
Selection("Fighter Combat", "fighter_combat", True),
)
yield Pretty([])
yield Footer()
def on_mount(self) -> None:
self.query_one(SelectionList).border_title = "Shall we play some games?"
self.query_one(Pretty).border_title = "Selected games"
@on(Mount)
@on(SelectionList.SelectedChanged)
def update_selected_view(self) -> None:
self.query_one(Pretty).update(self.query_one(SelectionList).selected)
if __name__ == "__main__":
SelectionListApp().run()
- Note that the
SelectionList
is typed asstr
, for the type of the values.
Reactive Attributes¶
Name | Type | Default | Description |
---|---|---|---|
highlighted |
int | None |
None |
The index of the highlighted selection. None means nothing is highlighted. |
Messages¶
The following messages will be posted as the user interacts with the list:
The following message will be posted if the content of
selected
changes, either by user
interaction or by API calls:
Bindings¶
The selection list widget defines the following bindings:
Key(s) | Description |
---|---|
space | Toggle the state of the highlighted selection. |
It inherits from OptionList
and so also inherits the following bindings:
Key(s) | Description |
---|---|
down | Move the highlight down. |
end | Move the highlight to the last option. |
enter | Select the current option. |
home | Move the highlight to the first option. |
pagedown | Move the highlight down a page of options. |
pageup | Move the highlight up a page of options. |
up | Move the highlight up. |
Component Classes¶
The selection list provides the following component classes:
Class | Description |
---|---|
selection-list--button |
Target the default button style. |
selection-list--button-selected |
Target a selected button style. |
selection-list--button-highlighted |
Target a highlighted button style. |
selection-list--button-selected-highlighted |
Target a highlighted selected button style. |
It inherits from OptionList
and so also
makes use of the following component classes:
Class | Description |
---|---|
option-list--option-disabled |
Target disabled options. |
option-list--option-highlighted |
Target the highlighted option. |
option-list--option-highlighted-disabled |
Target a disabled option that is also highlighted. |
option-list--option-hover |
Target an option that has the mouse over it. |
option-list--option-hover-disabled |
Target a disabled option that has the mouse over it. |
option-list--option-hover-highlighted |
Target a highlighted option that has the mouse over it. |
option-list--option-hover-highlighted-disabled |
Target a disabled highlighted option that has the mouse over it. |
option-list--separator |
Target the separators. |
textual.widgets.SelectionList
class
¶
Bases: Generic[SelectionType]
, OptionList
A vertical selection list that allows making multiple selections.
Parameters
Name | Type | Description | Default |
---|---|---|---|
*selections |
Selection | tuple[TextType, SelectionType] | tuple[TextType, SelectionType, bool]
|
The content for the selection list. |
()
|
name |
str | None
|
The name of the selection list. |
None
|
id |
str | None
|
The ID of the selection list in the DOM. |
None
|
classes |
str | None
|
The CSS classes of the selection list. |
None
|
disabled |
bool
|
Whether the selection list is disabled or not. |
False
|
BINDINGS
class-attribute
instance-attribute
¶
Key(s) | Description |
---|---|
space | Toggle the state of the highlighted selection. |
COMPONENT_CLASSES
class-attribute
¶
COMPONENT_CLASSES: set[str] = {
"selection-list--button",
"selection-list--button-selected",
"selection-list--button-highlighted",
"selection-list--button-selected-highlighted",
}
Class | Description |
---|---|
selection-list--button |
Target the default button style. |
selection-list--button-selected |
Target a selected button style. |
selection-list--button-highlighted |
Target a highlighted button style. |
selection-list--button-selected-highlighted |
Target a highlighted selected button style. |
selected
property
¶
The selected values.
This is a list of all of the values associated with selections in the list that are currently in the selected state.
SelectedChanged
class
¶
Bases: Generic[MessageSelectionType]
, Message
Message sent when the collection of selected values changes.
This message is sent when any change to the collection of selected values takes place; either by user interaction or by API calls.
SelectionHighlighted
class
¶
Bases: SelectionMessage
Message sent when a selection is highlighted.
Can be handled using on_selection_list_selection_highlighted
in a subclass of
SelectionList
or in a parent node in the DOM.
SelectionMessage
class
¶
Bases: Generic[MessageSelectionType]
, Message
Base class for all selection messages.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selection_list |
SelectionList
|
The selection list that owns the selection. |
required |
index |
int
|
The index of the selection that the message relates to. |
required |
control
property
¶
The selection list that sent the message.
This is an alias for
SelectionMessage.selection_list
and is used by the on
decorator.
selection
instance-attribute
¶
The highlighted selection.
selection_index
instance-attribute
¶
The index of the selection that the message relates to.
selection_list
instance-attribute
¶
The selection list that sent the message.
SelectionToggled
class
¶
Bases: SelectionMessage
Message sent when a selection is toggled.
Can be handled using on_selection_list_selection_toggled
in a subclass of
SelectionList
or in a parent node in the DOM.
Note
This message is only sent if the selection is toggled by user
interaction. See
SelectedChanged
for a message sent when any change (selected or deselected,
either by user interaction or by API calls) is made to the
selected values.
add_option
method
¶
Add a new selection option to the end of the list.
Parameters
Name | Type | Description | Default |
---|---|---|---|
item |
NewOptionListContent | Selection | tuple[TextType, SelectionType] | tuple[TextType, SelectionType, bool]
|
The new item to add. |
None
|
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
DuplicateID
|
If there is an attempt to use a duplicate ID. |
SelectionError
|
If the selection option is of the wrong form. |
add_options
method
¶
Add new selection options to the end of the list.
Parameters
Name | Type | Description | Default |
---|---|---|---|
items |
Iterable[NewOptionListContent | Selection | tuple[TextType, SelectionType] | tuple[TextType, SelectionType, bool]]
|
The new items to add. |
required |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
DuplicateID
|
If there is an attempt to use a duplicate ID. |
SelectionError
|
If one of the selection options is of the wrong form. |
clear_options
method
¶
Clear the content of the selection list.
Returns
Type | Description |
---|---|
Self
|
The |
deselect
method
¶
Mark the given selection as not selected.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selection |
Selection[SelectionType] | SelectionType
|
The selection to mark as not selected. |
required |
Returns
Type | Description |
---|---|
Self
|
The |
deselect_all
method
¶
get_option
method
¶
Get the selection option with the given ID.
Parameters
Name | Type | Description | Default |
---|---|---|---|
option_id |
str
|
The ID of the selection option to get. |
required |
Returns
Type | Description |
---|---|
Selection[SelectionType]
|
The selection option with the ID. |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no selection option has the given ID. |
get_option_at_index
method
¶
Get the selection option at the given index.
Parameters
Name | Type | Description | Default |
---|---|---|---|
index |
int
|
The index of the selection option to get. |
required |
Returns
Type | Description |
---|---|
Selection[SelectionType]
|
The selection option at that index. |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no selection option with the index. |
select
method
¶
Mark the given selection as selected.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selection |
Selection[SelectionType] | SelectionType
|
The selection to mark as selected. |
required |
Returns
Type | Description |
---|---|
Self
|
The |
select_all
method
¶
toggle
method
¶
Toggle the selected state of the given selection.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selection |
Selection[SelectionType] | SelectionType
|
The selection to toggle. |
required |
Returns
Type | Description |
---|---|
Self
|
The |
toggle_all
method
¶
MessageSelectionType
module-attribute
¶
The type for the value of a Selection
in a SelectionList
message.
SelectionType
module-attribute
¶
The type for the value of a Selection
in a SelectionList
Selection
class
¶
Bases: Generic[SelectionType]
, Option
A selection for a SelectionList
.
Parameters
Name | Type | Description | Default |
---|---|---|---|
prompt |
TextType
|
The prompt for the selection. |
required |
value |
SelectionType
|
The value for the selection. |
required |
initial_state |
bool
|
The initial selected state of the selection. |
False
|
id |
str | None
|
The optional ID for the selection. |
None
|
disabled |
bool
|
The initial enabled/disabled state. Enabled by default. |
False
|