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` ¶

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

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,
)

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.

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.

textual.binding

BindingIDString module-attribute ¶

BindingType module-attribute ¶

KeyString module-attribute ¶

Keymap module-attribute ¶

ActiveBinding ¶

binding instance-attribute ¶

enabled instance-attribute ¶

node instance-attribute ¶

tooltip class-attribute instance-attribute ¶

Binding dataclass ¶

action instance-attribute ¶

description class-attribute instance-attribute ¶

id class-attribute instance-attribute ¶

key instance-attribute ¶

key_display class-attribute instance-attribute ¶

priority class-attribute instance-attribute ¶

show class-attribute instance-attribute ¶

tooltip class-attribute instance-attribute ¶

make_bindings classmethod ¶

bindings ¶

parse_key ¶

with_key ¶

key ¶

key_display ¶

BindingError ¶

BindingsMap ¶

bindings ¶

key_to_bindings instance-attribute ¶

shown_keys property ¶

apply_keymap ¶

keymap ¶

bind ¶

keys ¶

action ¶

description ¶

show ¶

key_display ¶

priority ¶

copy ¶

from_keys classmethod ¶

keys ¶

get_bindings_for_key ¶

key ¶

merge classmethod ¶

bindings ¶

InvalidBinding ¶

KeymapApplyResult ¶

clashed_bindings instance-attribute ¶

NoBinding ¶

BindingIDString `module-attribute` ¶

BindingType `module-attribute` ¶

KeyString `module-attribute` ¶

Keymap `module-attribute` ¶

binding `instance-attribute` ¶

enabled `instance-attribute` ¶

node `instance-attribute` ¶

tooltip `class-attribute` `instance-attribute` ¶

Binding `dataclass` ¶

action `instance-attribute` ¶

description `class-attribute` `instance-attribute` ¶

id `class-attribute` `instance-attribute` ¶

key `instance-attribute` ¶

key_display `class-attribute` `instance-attribute` ¶

priority `class-attribute` `instance-attribute` ¶

show `class-attribute` `instance-attribute` ¶

tooltip `class-attribute` `instance-attribute` ¶

make_bindings `classmethod` ¶

`bindings` ¶

`key` ¶

`key_display` ¶

`bindings` ¶

key_to_bindings `instance-attribute` ¶

shown_keys `property` ¶

`keymap` ¶

`keys` ¶

`action` ¶

`description` ¶

`show` ¶

`key_display` ¶

`priority` ¶

from_keys `classmethod` ¶

`keys` ¶

`key` ¶

merge `classmethod` ¶

`bindings` ¶

clashed_bindings `instance-attribute` ¶