List Walker Classes

ListWalker

class urwid.ListWalker

get_focus() → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) currently in focus.

This default implementation relies on a focus attribute and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Returns:

(widget, position) or (None, None)

get_next(position: _K) → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) after position.

This default implementation relies on a next_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

get_prev(position: _K) → tuple[_V_co, _K] | tuple[None, None]

Return the (widget, position) before position.

This default implementation relies on a prev_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

List-like List Walkers

class urwid.SimpleFocusListWalker(contents: Iterable[_T], wrap_around: bool = False)

This class inherits MonitoredList which means it can be treated as a list.

Changes made to this object (when it is treated as a list) are detected automatically and will cause ListBox objects using this list walker to be updated.

Also, items added or removed before the widget in focus with normal list methods will cause the focus to be updated intelligently.

Parameters:

• contents – list to copy into this object

• wrap_around – if true, jumps to beginning/end of list on move

Raises:

ListWalkerError – contents is not iterable.

next_position(position: SupportsIndex) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Optional method for returning an iterable of positions.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: SupportsIndex) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

set_modified_callback(callback: Any) → NoReturn

This function inherited from MonitoredList is not implemented in SimpleFocusListWalker.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

class urwid.SimpleListWalker(contents: Iterable[_T], wrap_around: bool = False)

This class inherits MonitoredList which means it can be treated as a list.

Changes made to this object (when it is treated as a list) are detected automatically and will cause ListBox objects using this list walker to be updated.

Parameters:

• contents – list to copy into this object

• wrap_around – if true, jumps to beginning/end of list on move

Raises:

ListWalkerError – contents is not iterable.

property contents: Self

Return self.

Provides compatibility with old SimpleListWalker class.

next_position(position: int) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Optional method for returning an iterable of positions.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: int) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

Raises:

IndexError – if there is no widget at position

set_modified_callback(callback: Callable[[], Any]) → NoReturn

This function inherited from MonitoredList is not implemented in SimpleListWalker.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

Deque-like List Walkers

class urwid.SimpleFocusDequeWalker(contents: Iterable[_T], wrap_around: bool = False, maxlen: int | None = None)

A ListWalker backed by a MonitoredFocusDeque.

Mirrors SimpleFocusListWalker method-for-method, adapted to deque’s narrower API. See the performance caveat documented on SimpleDequeWalker – it applies equally here.

This class inherits MonitoredFocusDeque which means it can be treated as a deque.

Changes made to this object (when it is treated as a deque) are detected automatically and will cause ListBox objects using this list walker to be updated.

Also, items added or removed before the widget in focus with normal deque methods – including eviction caused by maxlen – will cause the focus to be updated intelligently.

Parameters:

• contents – iterable to copy into this object

• wrap_around – if true, jumps to beginning/end of deque on move

• maxlen – if set, bounds the deque’s length; the oldest items are silently evicted from the opposite end once full, and focus is adjusted to keep tracking a sensible item (see MonitoredFocusDeque)

Raises:

ListWalkerError – contents is not iterable.

next_position(position: SupportsIndex) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Optional method for returning an iterable of positions.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: SupportsIndex) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

set_modified_callback(callback: Any) → NoReturn

This function inherited from MonitoredFocusDeque is not implemented in SimpleFocusDequeWalker.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

class urwid.SimpleDequeWalker(contents: Iterable[_T], wrap_around: bool = False, maxlen: int | None = None)

A ListWalker backed by a MonitoredDeque.

Mirrors SimpleListWalker method-for-method, adapted to deque’s narrower API (in particular, maxlen-bounded eviction).

Note

ListWalker.get_focus()/ListWalker.get_next()/ListWalker.get_prev() (inherited, unmodified) index via self[position], and deque.__getitem__ is O(n) (linked-block structure) rather than a list’s O(1) – worth bearing in mind for a very large unbounded deque, though the bounded/maxlen scrollback use case this class targets is small enough that it does not matter in practice. No caching layer is provided.

This class inherits MonitoredDeque which means it can be treated as a deque.

Changes made to this object (when it is treated as a deque) are detected automatically and will cause ListBox objects using this list walker to be updated.

Parameters:

• contents – iterable to copy into this object

• wrap_around – if true, jumps to beginning/end of deque on move

• maxlen – if set, bounds the deque’s length; the oldest items are silently evicted from the opposite end once full

Raises:

ListWalkerError – contents is not iterable.

property contents: SimpleDequeWalker[_T]

Return self.

Provides compatibility with old SimpleListWalker class.

next_position(position: int) → int

Return position after position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no next position and wrap_around is false

positions(reverse: bool = False) → Iterable[int]

Optional method for returning an iterable of positions.

Parameters:

reverse – if true, return positions in reverse order

prev_position(position: int) → int

Return position before position.

Parameters:

position – position to start from

Raises:

IndexError – if there is no previous position and wrap_around is false

set_focus(position: int) → None

Set focus position.

Parameters:

position – position to focus

Raises:

IndexError – if there is no widget at position

set_modified_callback(callback: Callable[[], Any]) → NoReturn

This function inherited from MonitoredDeque is not implemented in SimpleDequeWalker.

Use connect_signal(list_walker, "modified", ...) instead.

Raises:

NotImplementedError – always

TreeWalker and Nodes

class urwid.TreeWalker(start_from: TreeNode[Any])

ListWalker-compatible class for displaying TreeWidgets

positions are TreeNodes.

start_from: TreeNode with the initial focus.

get_focus() → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]]

Return the (widget, position) currently in focus.

This default implementation relies on a focus attribute and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Returns:

(widget, position) or (None, None)

get_next(start_from: TreeNode[Any]) → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]] | tuple[None, None]

Return the (widget, position) after position.

This default implementation relies on a next_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

get_prev(start_from: TreeNode[Any]) → tuple[TreeWidget[TreeNode[Any]], TreeNode[Any]] | tuple[None, None]

Return the (widget, position) before position.

This default implementation relies on a prev_position() method and a __getitem__() method defined in a subclass.

Override and don’t call this method if these are not defined.

Parameters:

position – position to start from

Returns:

(widget, position) or (None, None)

class urwid.TreeNode(value: _T, parent: ParentNode[Any] | None = None, key: Hashable = None, depth: int | None = None)

Store tree contents and cache TreeWidget objects. A TreeNode consists of the following elements: * key: accessor token for parent nodes * value: subclass-specific data * parent: a TreeNode which contains a pointer back to this object * widget: The widget used to render the object

get_widget(reload: bool = False) → TreeWidget[Self]

Return the widget for this node.

load_parent() → ParentNode[Any]

Provide TreeNode with a parent for the current node.

This function is only required if the tree was instantiated from a child node (virtual function)

Raises:

TreeWidgetError – the subclass does not override this method.

class urwid.ParentNode(value: Any, parent: ParentNode[Any] | None = None, key: Hashable = None, depth: int | None = None)

Maintain sort order for TreeNodes.

change_child_key(oldkey: Hashable, newkey: Hashable) → None

Rename a child, moving it from oldkey to newkey.

Raises:

TreeWidgetError – newkey is already used by another child.

get_child_index(key: Hashable) → int

Return the position of the child key among the child keys.

Raises:

TreeWidgetError – key is not a child of this node.

get_child_keys(reload: bool = False) → Sequence[Hashable]

Return a possibly ordered list of child keys

get_child_node(key: Hashable, reload: bool = False) → TreeNode[Any]

Return the child node for a given key. Create if necessary.

get_child_widget(key: Hashable) → TreeWidget[TreeNode[Any]]

Return the widget for a given key. Create if necessary.

get_first_child() → TreeNode[Any]

Return the first TreeNode in the directory.

get_last_child() → TreeNode[Any]

Return the last TreeNode in the directory.

has_children() → bool

Does this node have any children?

load_child_keys() → Sequence[Hashable]

Provide ParentNode with an ordered list of child keys (virtual function)

Raises:

TreeWidgetError – the subclass does not override this method.

load_child_node(key: Hashable) → TreeNode[Any]

Load the child node for a given key (virtual function)

Raises:

TreeWidgetError – the subclass does not override this method.

next_child(key: Hashable) → TreeNode[Any] | None

Return the next child node in index order from the given key.

prev_child(key: Hashable) → TreeNode[Any] | None

Return the previous child node in index order from the given key.

set_child_node(key: Hashable, node: TreeNode[Any]) → None

Set the child node for a given key.

Useful for bottom-up, lazy population of a tree.