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
, 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-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.OptionList
class
¶
Bases: ScrollView
A vertical option list with bounce-bar highlighting.
Parameters
Parameter | Default | Description |
---|---|---|
*content
NewOptionListContent
|
()
|
The content for the option list. |
name
str | None
|
None
|
The name of the option list. |
id
str | None
|
None
|
The ID of the option list in the DOM. |
classes
str | None
|
None
|
The CSS classes of the option list. |
disabled
bool
|
False
|
Whether the option list is disabled or not. |
wrap
bool
|
True
|
Should prompts be auto-wrapped? |
BINDINGS
class-attribute
¶
BINDINGS: list[BindingType] = [
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: set[str] = {
"option-list--option",
"option-list--option-disabled",
"option-list--option-highlighted",
"option-list--option-highlighted-disabled",
"option-list--option-hover",
"option-list--option-hover-disabled",
"option-list--option-hover-highlighted",
"option-list--option-hover-highlighted-disabled",
"option-list--separator",
}
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. |
highlighted
instance-attribute
class-attribute
¶
The index of the currently-highlighted option, or None
if no option is highlighted.
OptionHighlighted
class
¶
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.
OptionMessage
class
¶
Bases: Message
Base class for all option messages.
Parameters
Parameter | Default | Description |
---|---|---|
option_list
OptionList
|
required | The option list that owns the option. |
index
int
|
required | The index of the option that the message relates to. |
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
instance-attribute
¶
The highlighted option.
option_id
instance-attribute
¶
The ID of the option that the message relates to.
option_index
instance-attribute
¶
The index of the option that the message relates to.
option_list
instance-attribute
¶
The option list that sent the message.
OptionSelected
class
¶
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.
action_select
method
¶
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
method
¶
Add a new option to the end of the option list.
Parameters
Parameter | Default | Description |
---|---|---|
item
NewOptionListContent
|
None
|
The new item to add. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
DuplicateID
|
If there is an attempt to use a duplicate ID. |
add_options
method
¶
Add new options to the end of the option list.
Parameters
Parameter | Default | Description |
---|---|---|
items
Iterable[NewOptionListContent]
|
required | The new items to add. |
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
method
¶
Clear the content of the option list.
Returns
Type | Description |
---|---|
Self
|
The |
disable_option
method
¶
Disable the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to disable. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
disable_option_at_index
method
¶
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
method
¶
Enable the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to enable. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
enable_option_at_index
method
¶
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
method
¶
Get the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to get. |
Returns
Type | Description |
---|---|
Option
|
The option with the ID. |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
get_option_at_index
method
¶
Get the option at the given index.
Parameters
Parameter | Default | Description |
---|---|---|
index
int
|
required | The index of the option to get. |
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
method
¶
Get the index of the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to get the index of. |
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
method
¶
Remove the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to remove. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
remove_option_at_index
method
¶
Remove the option at the given index.
Parameters
Parameter | Default | Description |
---|---|---|
index
int
|
required | The index of the option to remove. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
replace_option_prompt
method
¶
Replace the prompt of the option with the given ID.
Parameters
Parameter | Default | Description |
---|---|---|
option_id
str
|
required | The ID of the option to replace the prompt of. |
prompt
RenderableType
|
required | The new prompt for the option. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If no option has the given ID. |
replace_option_prompt_at_index
method
¶
Replace the prompt of the option at the given index.
Parameters
Parameter | Default | Description |
---|---|---|
index
int
|
required | The index of the option to replace the prompt of. |
prompt
RenderableType
|
required | The new prompt for the option. |
Returns
Type | Description |
---|---|
Self
|
The |
Raises
Type | Description |
---|---|
OptionDoesNotExist
|
If there is no option with the given index. |
scroll_to_highlight
method
¶
Ensure that the highlighted option is in view.
Parameters
Parameter | Default | Description |
---|---|---|
top
bool
|
False
|
Scroll highlight to top of the list. |
validate_highlighted
method
¶
Validate the highlighted
property value on access.
watch_highlighted
method
¶
React to the highlighted option having changed.
watch_show_vertical_scrollbar
method
¶
Handle the vertical scrollbar visibility status changing.
show_vertical_scrollbar
is watched because it has an impact on the
available width in which to render the renderables that make up the
options in the list. If a vertical scrollbar appears or disappears
we need to recalculate all the lines that make up the list.
DuplicateID
class
¶
Bases: Exception
Raised if a duplicate ID is used when adding options to an option list.
Option
class
¶
Class that holds the details of an individual option.
Parameters
Parameter | Default | Description |
---|---|---|
prompt
RenderableType
|
required | The prompt for the option. |
id
str | None
|
None
|
The optional ID for the option. |
disabled
bool
|
False
|
The initial enabled/disabled state. Enabled by default. |
set_prompt
method
¶
Set the prompt for the option.
Parameters
Parameter | Default | Description |
---|---|---|
prompt
RenderableType
|
required | The new prompt for the option. |
OptionDoesNotExist
class
¶
Bases: Exception
Raised when a request has been made for an option that doesn't exist.
Separator
class
¶
Class used to add a separator to an OptionList.