Skip to content

textual.binding

This module contains the Binding class and related objects.

See bindings in the guide for details.

BindingIDString module-attribute

BindingIDString = str

The ID of a Binding defined somewhere in the application.

Corresponds to the id parameter of the Binding class.

BindingType module-attribute

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

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

KeyString module-attribute

KeyString = str

A string that represents a key binding.

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

Keymap module-attribute

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

The binding information.

enabled instance-attribute

enabled

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

node instance-attribute

node

The node where the binding is defined.

tooltip class-attribute instance-attribute

tooltip = ''

Optional tooltip shown in Footer.

Binding dataclass

Binding(
    key,
    action,
    description="",
    show=True,
    key_display=None,
    priority=False,
    tooltip="",
    id=None,
    system=False,
)

The configuration of a key binding.

action instance-attribute

action

Action to bind to.

description class-attribute instance-attribute

description = ''

Description of action.

id class-attribute instance-attribute

id = 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

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 = 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 = False

Enable priority binding for this key.

show class-attribute instance-attribute

show = True

Show the action in Footer, or False to hide.

system class-attribute instance-attribute

system = False

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

tooltip class-attribute instance-attribute

tooltip = ''

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 in to 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 = {}

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

shown_keys property

shown_keys

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

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

NoBinding

Bases: Exception

A binding was not found.