[go: up one dir, main page]
Skip to content

ListView

Added in version 0.6.0

Displays a vertical list of ListItems which can be highlighted and selected. Supports keyboard navigation.

  • Focusable
  • Container

Example

The example below shows an app with a simple ListView.

ListViewExample One Two Three ▏^p palette 

from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, ListItem, ListView


class ListViewExample(App):
    CSS_PATH = "list_view.tcss"

    def compose(self) -> ComposeResult:
        yield ListView(
            ListItem(Label("One")),
            ListItem(Label("Two")),
            ListItem(Label("Three")),
        )
        yield Footer()


if __name__ == "__main__":
    app = ListViewExample()
    app.run()

Screen {
    align: center middle;
}

ListView {
    width: 30;
    height: auto;
    margin: 2 2;
}

Label {
    padding: 1 2;
}

Reactive Attributes

Name Type Default Description
index int 0 The currently highlighted index.

Messages

Bindings

The list view widget defines the following bindings:

Key(s) Description
enter Select the current item.
up Move the cursor up.
down Move the cursor down.

Component Classes

This widget has no component classes.

Bases: VerticalScroll

A vertical list view widget.

Displays a vertical list of ListItems which can be highlighted and selected using the mouse or keyboard.

Attributes:

Name Type Description
index

The index in the list that's currently highlighted.

Parameters:

Name Type Description Default

*children

ListItem

The ListItems to display in the list.

 ()

initial_index

int | None

The index that should be highlighted when the list is first mounted.

 0

name

str | None

The name of the widget.

 None

id

str | None

The unique ID of the widget used in CSS/query selection.

 None

classes

str | None

The CSS classes of the widget.

 None

disabled

bool

Whether the ListView is disabled or not.

 False

BINDINGS class-attribute 

BINDINGS = [
    Binding("enter", "select_cursor", "Select", show=False),
    Binding("up", "cursor_up", "Cursor up", show=False),
    Binding(
        "down", "cursor_down", "Cursor down", show=False
    ),
]
Key(s) Description
enter Select the current item.
up Move the cursor up.
down Move the cursor down.

highlighted_child property 

highlighted_child

The currently highlighted ListItem, or None if nothing is highlighted.

index class-attribute instance-attribute 

index = reactive[Optional[int]](None, init=False)

The index of the currently highlighted item.

Highlighted 

Highlighted(list_view, item)

Bases: Message

Posted when the highlighted item changes.

Highlighted item is controlled using up/down keys. Can be handled using on_list_view_highlighted in a subclass of ListView or in a parent widget in the DOM.

ALLOW_SELECTOR_MATCH class-attribute instance-attribute 

ALLOW_SELECTOR_MATCH = {'item'}

Additional message attributes that can be used with the on decorator.

control property 

control

The view that contains the item highlighted.

This is an alias for Highlighted.list_view and is used by the on decorator.

item instance-attribute 

item = item

The highlighted item, if there is one highlighted.

list_view instance-attribute 

list_view = list_view

The view that contains the item highlighted.

Selected 

Selected(list_view, item)

Bases: Message

Posted when a list item is selected, e.g. when you press the enter key on it.

Can be handled using on_list_view_selected in a subclass of ListView or in a parent widget in the DOM.

ALLOW_SELECTOR_MATCH class-attribute instance-attribute 

ALLOW_SELECTOR_MATCH = {'item'}

Additional message attributes that can be used with the on decorator.

control property 

control

The view that contains the item selected.

This is an alias for Selected.list_view and is used by the on decorator.

item instance-attribute 

item = item

The selected item.

list_view instance-attribute 

list_view = list_view

The view that contains the item selected.

action_cursor_down 

action_cursor_down()

Highlight the next item in the list.

action_cursor_up 

action_cursor_up()

Highlight the previous item in the list.

action_select_cursor 

action_select_cursor()

Select the current item in the list.

append 

append(item)

Append a new ListItem to the end of the ListView.

Parameters:

Name Type Description Default

item

ListItem

The ListItem to append.

 required

Returns:

Type Description
AwaitMount

An awaitable that yields control to the event loop until the DOM has been updated with the new child item.

clear 

clear()

Clear all items from the ListView.

Returns:

Type Description
AwaitRemove

An awaitable that yields control to the event loop until the DOM has been updated to reflect all children being removed.

extend 

extend(items)

Append multiple new ListItems to the end of the ListView.

Parameters:

Name Type Description Default

items

Iterable[ListItem]

The ListItems to append.

 required

Returns:

Type Description
AwaitMount

An awaitable that yields control to the event loop until the DOM has been updated with the new child items.

insert 

insert(index, items)

Insert new ListItem(s) to specified index.

Parameters:

Name Type Description Default

index

int

index to insert new ListItem.

 required

items

Iterable[ListItem]

The ListItems to insert.

 required

Returns:

Type Description
AwaitMount

An awaitable that yields control to the event loop until the DOM has been updated with the new child item.

pop 

pop(index=None)

Remove last ListItem from ListView or Remove ListItem from ListView by index

Parameters:

Name Type Description Default

index

Optional[int]

index of ListItem to remove from ListView

 None

Returns:

Type Description
AwaitRemove

An awaitable that yields control to the event loop until the DOM has been updated to reflect item being removed.

remove_items 

remove_items(indices)

Remove ListItems from ListView by indices

Parameters:

Name Type Description Default

indices

Iterable[int]

index(s) of ListItems to remove from ListView

 required

Returns:

Type Description
AwaitRemove

An awaitable object that waits for the direct children to be removed.

validate_index 

validate_index(index)

Clamp the index to the valid range, or set to None if there's nothing to highlight.

Parameters:

Name Type Description Default

index

int | None

The index to clamp.

 required

Returns:

Type Description
int | None

The clamped index.

watch_index 

watch_index(old_index, new_index)

Updates the highlighting when the index changes.