OptionList¶
Added in version 0.17.0
A widget for showing a vertical list of Rich renderable options.
- Focusable
- Container
Examples¶
Options as simple strings¶
An OptionList
can be constructed with a simple collection of string
options:
from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList
class OptionListApp(App[None]):
CSS_PATH = "option_list.tcss"
def compose(self) -> ComposeResult:
yield Header()
yield OptionList(
"Aerilon",
"Aquaria",
"Canceron",
"Caprica",
"Gemenon",
"Leonis",
"Libran",
"Picon",
"Sagittaron",
"Scorpia",
"Tauron",
"Virgon",
)
yield Footer()
if __name__ == "__main__":
OptionListApp().run()
Options as Option
instances¶
For finer control over the options, the Option
class can be used; this
allows for setting IDs, setting initial disabled state, etc. The Separator
class can be used to add separator lines between options.
from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList
from textual.widgets.option_list import Option, Separator
class OptionListApp(App[None]):
CSS_PATH = "option_list.tcss"
def compose(self) -> ComposeResult:
yield Header()
yield OptionList(
Option("Aerilon", id="aer"),
Option("Aquaria", id="aqu"),
Separator(),
Option("Canceron", id="can"),
Option("Caprica", id="cap", disabled=True),
Separator(),
Option("Gemenon", id="gem"),
Separator(),
Option("Leonis", id="leo"),
Option("Libran", id="lib"),
Separator(),
Option("Picon", id="pic"),
Separator(),
Option("Sagittaron", id="sag"),
Option("Scorpia", id="sco"),
Separator(),
Option("Tauron", id="tau"),
Separator(),
Option("Virgon", id="vir"),
)
yield Footer()
if __name__ == "__main__":
OptionListApp().run()
Options as Rich renderables¶
Because the prompts for the options can be Rich renderables, this means they can be any height you wish. As an example, here is an option list comprised of Rich tables:
from __future__ import annotations
from rich.table import Table
from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList
COLONIES: tuple[tuple[str, str, str, str], ...] = (
("Aerilon", "Demeter", "1.2 Billion", "Gaoth"),
("Aquaria", "Hermes", "75,000", "None"),
("Canceron", "Hephaestus", "6.7 Billion", "Hades"),
("Caprica", "Apollo", "4.9 Billion", "Caprica City"),
("Gemenon", "Hera", "2.8 Billion", "Oranu"),
("Leonis", "Artemis", "2.6 Billion", "Luminere"),
("Libran", "Athena", "2.1 Billion", "None"),
("Picon", "Poseidon", "1.4 Billion", "Queenstown"),
("Sagittaron", "Zeus", "1.7 Billion", "Tawa"),
("Scorpia", "Dionysus", "450 Million", "Celeste"),
("Tauron", "Ares", "2.5 Billion", "Hypatia"),
("Virgon", "Hestia", "4.3 Billion", "Boskirk"),
)
class OptionListApp(App[None]):
CSS_PATH = "option_list.tcss"
@staticmethod
def colony(name: str, god: str, population: str, capital: str) -> Table:
table = Table(title=f"Data for {name}", expand=True)
table.add_column("Patron God")
table.add_column("Population")
table.add_column("Capital City")
table.add_row(god, population, capital)
return table
def compose(self) -> ComposeResult:
yield Header()
yield OptionList(*[self.colony(*row) for row in COLONIES])
yield Footer()
if __name__ == "__main__":
OptionListApp().run()
Reactive Attributes¶
Name | Type | Default | Description |
---|---|---|---|
highlighted |
int | None |
None |
The index of the highlighted option. None means nothing is highlighted. |
Messages¶
Both of the messages above inherit from the common base OptionList.OptionMessage
, so refer to its documentation to see what attributes are available.
Bindings¶
The option list widget defines 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 option list provides the following component classes:
Class | Description |
---|---|
option-list--option-disabled |
Target disabled options. |
option-list--option-highlighted |
Target the highlighted option. |
option-list--option-hover |
Target an option that has the mouse over it. |
option-list--separator |
Target the separators. |
Bases: ScrollView
A vertical option list with bounce-bar highlighting.
BINDINGS
class-attribute
¶
BINDINGS = [
Binding("down", "cursor_down", "Down", show=False),
Binding("end", "last", "Last", show=False),
Binding("enter", "select", "Select", show=False),
Binding("home", "first", "First", show=False),
Binding(
"pagedown", "page_down", "Page down", show=False
),
Binding("pageup", "page_up", "Page up", show=False),
Binding("up", "cursor_up", "Up", show=False),
]
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
class-attribute
¶
COMPONENT_CLASSES = {
"option-list--option",
"option-list--option-disabled",
"option-list--option-highlighted",
"option-list--option-hover",
"option-list--separator",
}
Class | Description |
---|---|
option-list--option-disabled |
Target disabled options. |
option-list--option-highlighted |
Target the highlighted option. |
option-list--option-hover |
Target an option that has the mouse over it. |
option-list--separator |
Target the separators. |
highlighted
class-attribute
instance-attribute
¶
highlighted = reactive['int | None'](None)
The index of the currently-highlighted option, or None
if no option is highlighted.
OptionHighlighted
¶
OptionHighlighted(option_list, index)
Bases: OptionMessage
Message sent when an option is highlighted.
Can be handled using on_option_list_option_highlighted
in a subclass of
OptionList
or in a parent node in the DOM.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
OptionList
|
The option list that owns the option. |
required |
|
int
|
The index of the option that the message relates to. |
required |
OptionMessage
¶
OptionMessage(option_list, index)
Bases: Message
Base class for all option messages.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
OptionList
|
The option list that owns the option. |
required |
|
int
|
The index of the option that the message relates to. |
required |
control
property
¶
The option list that sent the message.
This is an alias for OptionMessage.option_list
and is used by the on
decorator.
option_index
instance-attribute
¶
The index of the option that the message relates to.
OptionSelected
¶
OptionSelected(option_list, index)
Bases: OptionMessage
Message sent when an option is selected.
Can be handled using on_option_list_option_selected
in a subclass of
OptionList
or in a parent node in the DOM.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
OptionList
|
The option list that owns the option. |
required |
|
int
|
The index of the option that the message relates to. |
required |
action_select
¶
Select the currently-highlighted option.
If no option is selected, then nothing happens. If an option is selected, a OptionList.OptionSelected message will be posted.
add_option
¶
add_option(item=None)
Add a new option to the end of the option list.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
NewOptionListContent
|
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. |
add_options
¶
add_options(items)
Add new options to the end of the option list.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Iterable[NewOptionListContent]
|
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. |
Note
All options are checked for duplicate IDs before any option is added. A duplicate ID will cause none of the passed items to be added to the option list.
clear_options
¶
Clear the content of the option list.
Returns:
Type | Description |
---|---|
Self
|
The |
disable_option
¶
disable_option(option_id)
Disable the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to disable. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
disable_option_at_index
¶
Disable the option at the given index.
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
enable_option
¶
enable_option(option_id)
Enable the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to enable. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
enable_option_at_index
¶
Enable the option at the given index.
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
get_option
¶
get_option(option_id)
Get the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to get. |
required |
Returns:
Type | Description |
---|---|
Option
|
The option with the ID. |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
get_option_at_index
¶
get_option_at_index(index)
Get the option at the given index.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
int
|
The index of the option to get. |
required |
Returns:
Type | Description |
---|---|
Option
|
The option at that index. |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
get_option_index
¶
get_option_index(option_id)
Get the index of the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to get the index of. |
required |
Returns:
Type | Description |
---|---|
int
|
The index of the item with the given ID. |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
remove_option
¶
remove_option(option_id)
Remove the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to remove. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
remove_option_at_index
¶
remove_option_at_index(index)
Remove the option at the given index.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
int
|
The index of the option to remove. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
replace_option_prompt
¶
Replace the prompt of the option with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the option to replace the prompt of. |
required |
|
RenderableType
|
The new prompt for the option. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
replace_option_prompt_at_index
¶
Replace the prompt of the option at the given index.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
int
|
The index of the option to replace the prompt of. |
required |
|
RenderableType
|
The new prompt for the option. |
required |
Returns:
Type | Description |
---|---|
Self
|
The |
Raises:
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
validate_highlighted
¶
Validate the highlighted
property value on access.
DuplicateID
¶
Bases: Exception
Raised if a duplicate ID is used when adding options to an option list.
Option
¶
OptionDoesNotExist
¶
Bases: Exception
Raised when a request has been made for an option that doesn't exist.
Separator
¶
Class used to add a separator to an OptionList.