textual.binding

This module contains the Binding class and related objects.

See bindings in the guide for details.

BindingIDString module-attribute

BindingIDString: TypeAlias = str

The ID of a Binding defined somewhere in the application.

Corresponds to the id parameter of the Binding class.

BindingType module-attribute

BindingType: TypeAlias = (
    "Binding | tuple[str, str] | tuple[str, str, str]"
)

The possible types of a binding found in the BINDINGS class variable.

KeyString module-attribute

KeyString: TypeAlias = str

A string that represents a key binding.

For example, "x", "ctrl+i", "ctrl+shift+a", "ctrl+j,space,x", etc.

Keymap module-attribute

Keymap = Mapping[BindingIDString, KeyString]

A mapping of binding IDs to key strings, used for overriding default key bindings.

ActiveBinding

Bases: NamedTuple

Information about an active binding (returned from active_bindings).

binding instance-attribute

binding: Binding

The binding information.

enabled instance-attribute

enabled: bool

Is the binding enabled? (enabled bindings are typically rendered dim)

node instance-attribute

node: DOMNode

The node where the binding is defined.

tooltip class-attribute instance-attribute

tooltip: str = ''

Optional tooltip shown in Footer.

Binding dataclass

The configuration of a key binding.

action instance-attribute

action: str

Action to bind to.

description class-attribute instance-attribute

description: str = ''

Description of action.

id class-attribute instance-attribute

id: str | None = None

ID of the binding. Intended to be globally unique, but uniqueness is not enforced.

If specified in the App's keymap then Textual will use this ID to lookup the binding, and substitute the key property of the Binding with the key specified in the keymap.

key instance-attribute

key: str

Key to bind. This can also be a comma-separated list of keys to map multiple keys to a single action.

key_display class-attribute instance-attribute

key_display: str | None = None

How the key should be shown in footer.

If None, the display of the key will use the result of App.get_key_display.

If overridden in a keymap then this value is ignored.

priority class-attribute instance-attribute

priority: bool = False

Enable priority binding for this key.

show class-attribute instance-attribute

show: bool = True

Show the action in Footer, or False to hide.

system class-attribute instance-attribute

system: bool = False

Make this binding a system binding, which removes it from the key panel.

tooltip class-attribute instance-attribute

tooltip: str = ''

Optional tooltip to show in footer.

make_bindings classmethod

make_bindings(bindings)

Convert a list of BindingType (the types that can be specified in BINDINGS) into an Iterable[Binding].

Compound bindings like "j,down" will be expanded into 2 Binding instances.

Parameters:

Name	Type	Description	Default
bindings	Iterable[BindingType]	An iterable of BindingType.	required

Returns:

Type	Description
Iterable[Binding]	An iterable of Binding.

parse_key

parse_key()

Parse a key into a list of modifiers, and the actual key.

Returns:

Type	Description
tuple[list[str], str]	A tuple of (MODIFIER LIST, KEY).

with_key

with_key(key, key_display=None)

Return a new binding with the key and key_display set to the specified values.

Parameters:

Name	Type	Description	Default
key	str	The new key to set.	required
key_display	str | None	The new key display to set.	None

Returns:

Type	Description
Binding	A new binding with the key set to the specified value.

BindingError

Bases: Exception

A binding related error.

BindingsMap

BindingsMap(bindings=None)

Manage a set of bindings.

Parameters:

Name	Type	Description	Default
bindings	Iterable[BindingType] | None	An optional set of initial bindings.	None

Note

The iterable of bindings can contain either a Binding instance, or a tuple of 3 values mapping to the first three properties of a Binding.

key_to_bindings instance-attribute

key_to_bindings: dict[str, list[Binding]] = {}

Mapping of key (e.g. "ctrl+a") to list of bindings for that key.

shown_keys property

shown_keys: list[Binding]

A list of bindings for shown keys.

apply_keymap

apply_keymap(keymap)

Replace bindings for keys that are present in keymap.

Preserves existing bindings for keys that are not in keymap.

Parameters:

Name	Type	Description	Default
keymap	Keymap	A keymap to overlay.	required

Returns:

Name	Type	Description
KeymapApplyResult	KeymapApplyResult	The result of applying the keymap, including any clashed bindings.

bind

bind(
    keys,
    action,
    description="",
    show=True,
    key_display=None,
    priority=False,
)

Bind keys to an action.

Parameters:

Name	Type	Description	Default
keys	str	The keys to bind. Can be a comma-separated list of keys.	required
action	str	The action to bind the keys to.	required
description	str	An optional description for the binding.	''
show	bool	A flag to say if the binding should appear in the footer.	True
key_display	str | None	Optional string to display in the footer for the key.	None
priority	bool	Is this a priority binding, checked form app down to focused widget?	False

copy

copy()

Return a copy of this instance.

Return

New bindings object.

from_keys classmethod

from_keys(keys)

Construct a BindingsMap from a dict of keys and bindings.

Parameters:

Name	Type	Description	Default
keys	dict[str, list[Binding]]	A dict that maps a key on to a list of Binding objects.	required

Returns:

Type	Description
BindingsMap	New BindingsMap

get_bindings_for_key

get_bindings_for_key(key)

Get a list of bindings for a given key.

Parameters:

Name	Type	Description	Default
key	str	Key to look up.	required

Raises:

Type	Description
NoBinding	If the binding does not exist.

Returns:

Type	Description
list[Binding]	A list of bindings associated with the key.

merge classmethod

merge(bindings)

Merge a bindings.

Parameters:

Name	Type	Description	Default
bindings	Iterable[BindingsMap]	A number of bindings.	required

Returns:

Type	Description
BindingsMap	New BindingsMap.

InvalidBinding

Bases: Exception

Binding key is in an invalid format.

KeymapApplyResult

Bases: NamedTuple

The result of applying a keymap.

clashed_bindings instance-attribute

clashed_bindings: set[Binding]

A list of bindings that were clashed and replaced by the keymap.

NoBinding

Bases: Exception

A binding was not found.