Keymaps

[darrenburns]

Keybindings in Textual applications are statically declared via the BINDINGS ClassVar at the App, Screen, or Widget level. There is currently no API which allows modifying the chosen keybindings after the developer adds it to BINDINGS.

Here, I sketch out an API which would allow developers to declare "overrides" for those statically declared keys. It aims to resolve one of the most common requests I see from Textual app end-users: "hey - can you please make it such that I can press X instead of Y to perform Z"?

This is not an attempt to add ultimate flexibility to the bindings system, such as the ability to customise any binding in any way at runtime. That is a considerably more niche (and harder to achieve) requirement!

Feel free to leave thoughts below!

Motivation

Simply put, it's impossible for a Textual app developer to choose a set of keybindings which satisfies all user preferences and environments.

• Expectations: Often, users simply dislike the choices made by the app developer as it may not match their expectations.
• Muscle-memory: A keybinding choice made by an app developer may clash with the muscle memory of an end-user. Changing the binding to suit one user may cause a similar clash for another.
• Multiplexer clashes: tmux and Zellij users (a very terminal-centric group of users!) often report that keybinds clash with their multiplexer, leaving Textual apps completely unusable via keyboard with no workarounds.
• Terminal emulator clashes: Bindings may also clash at the terminal emulator level. Users of Posting have reported clashes with WezTerm bindings.
• OS keybinding clashes: Bindings can clash with some default OS-level bindings. A developer working on Linux or Windows for example, may assign ctrl+up to an action, unaware that MacOS will eat this keypress by default.
• Kitty keyboard protocol: Textual supports the Kitty keyboard protocol, but we can't guarantee the same about the end-user's terminal emulator. As an end-user with no way to reassign bindings, your only option at the moment is to ask your terminal emulator to translate the keypress into the correct escape sequence (a tough ask which may not even be possible in some emulators), or open an issue and ask the app developer to add a non-Kitty protocol alternative binding.
• Regional keyboard differences: The developer may assign bindings which seem reasonable on their keyboard layout, but for users from other countries, may be difficult or impossible. We encountered this problem with our original choice of ctrl+\ for the command palette, which seemed like a good choice with our UK and US keyboard layouts, but caused problems for folks with some European keyboard layouts.
• Keyboard layout differences: To offer good UX to end-users, it's common to bind functionality to the "home keys". This assumes a QWERTY layout, however. What is a comfortable, quickly accessible binding on my QWERTY keyboard may be a finger contortion exercise for those on alternative layouts.

Anecdotally, requests to change keybindings are probably the most common issue that falls under Textual's "remit" that has been asked in issues and discussions for my own projects. We've also seen popular Textual-based applications such as Harlequin roll their own system to allow end-users to customise keybinds, further suggesting the need for such an API.

Proposal

Binding IDs

In order to update a specific binding, we need to be able to reference it.

The Binding object will be extended with a new id parameter which will be used to identify it. Textual will not enforce uniqueness of these binding IDs in any way. In the future, this ID could be used as part of a more comprehensive runtime binding update API.

Here's an example of some bindings defined at the App-level that have binding IDs:

class CounterBot3000(App[None]):
    BINDINGS = [
        Binding("ctrl+i", "increment", "Increment", id="increment"),
        Binding("ctrl+d", "decrement", "Decrement", id="decrement"),
    ]
    ...

and some at the Widget-level:

class CountInput(Input):
    Bindings = [
        Binding("ctrl+j", "submit_count", "Submit", id="count.submit")
    ]
	...

These IDs are my own choices. Developers can choose any string ID they wish in order to reference the binding.

Bindings with no key assigned

The key parameter of Binding will accept None as a valid value.
This will indicate the Binding is not currently mapped to an action, but that it can be mapped via a keymap.

Keymap API

This API makes it easy for developers to allow end-users to override the default bindings (those defined via the BINDINGS classvar) in their app.

A Keymap maps binding IDs to the key combination required to trigger those bindings. An App can have a single keymap, which should be returned from the load_keymap method. The default keymap is empty, which means none of the default bindings will be overridden.

class CounterBot3000(App[None]):

    def load_keymap(self) -> Keymap:
        return Keymap({
            "increment": "plus",
            "count.submit": "alt+enter",
            "foo.bar": "alt+x",
            "bar.baz": None,  # unbind
        })

The keymap will override the ctrl+j keybinding in the CountInput which we gave the binding ID "count.submit" with alt+enter. It'll replace the binding with ID "increment", so that you instead have to press + to activate it.

A binding ID mapped to None in the keymap will unbind that binding.

Since a keymap is just instantiated with a dict, it's easy to load from an external source (config file/keymap file/external API).

The Keymap is returned from a method on App because it suggest to the developer that the keymap is loaded once, by the app, on startup. If it were a reactive, it'd suggest that keymaps can be swapped out on the fly.

It may be possible to do this swapping at runtime (for example, swap out a bunch of the text_area.* bindings in the keymap when we change from insert to normal mode in a modal text editor), but that would require further research on my part. Perhaps those kind of runtime changes are a different API altogether, however.

If a binding ID supplied in the keymap is not valid, it does not cause an exception as doing so may cause backwards compatibility issues for Textual app developers as they make changes which may not align with their users config/keymaps - likely sourced from an external file. If a developer wishes, they can track the binding IDs used themselves and warn end-users if necessary if an invalid binding ID is supplied.

Questions

What happens if two binding IDs are the same?

If two Bindings share an ID, they'll both be updated should that binding ID appear in the Keymap. This could actually be useful as a means of ensuring consistent keybindings across an app. For example, Posting has several subclasses of Input. If all these Input subclasses shared an ID for "submitting" the Input, then a single entry in the Keymap would apply to all of the Input subclasses, ensuring the same key is used for submission across the whole application.

How do Binding IDs work when a widget is subclassed?

Applying the overrides from the keymap happens before we attempt to inherit bindings from a parent widget. After the keymap is applied, binding inheritance works as normal.

Let's work through some different cases:

Same binding ID in child and parent:

• Input with binding Binding("ctrl+j", "submit", id="submit")
• MyInput(Input) with Binding("enter", "submit", id="submit")

With the keymap Keymap({"submit": "ctrl+o"}), all Input and MyInput widgets in the app will be updated such that only ctrl+o will submit. The original bindings (ctrl+j on Input and enter on MyInput) are lost.

Child has a different ID:

• Input with binding Binding("ctrl+j", "submit", id="submit")
• MyInput(Input) with Binding("enter", "submit", id="foo.submit")

With a keymap Keymap({"submit": "ctrl+o"}), the Input will have it's "submit" binding overridden to ctrl+o. Since MyInput inherits the "submit" binding from Input, ctrl+o will work their too. As far as Textual is concerned (even today), these are "different" bindings.

• Input with Binding("ctrl+j", "submit", id="submit")
• MyInput(Input) with Binding("enter", "submit")

With Keymap({"submit": "ctrl+o"}), the binding in Input will be updated to ctrl+o, and that will be inherited by MyInput.

Overriding a binding with same key, action, but no ID:

This case is a little harder to reason about.

• Input with Binding("ctrl+j", "submit", id="submit")
• MyInput(Input) with Binding("ctrl+j", "submit")

With Keymap({"submit": "ctrl+o"}): The submit binding in the parent Input should be overridden before the "inheritance" takes place. (Inheritance takes place when the same key is used, it's unrelated to binding IDs). Since the keys no longer match between parent and child, the inheritance of the binding no longer occurs.

What about comma-separated bindings

Some bindings are declared like Binding("down,j", ...) (i.e. press either down or j to perform the action). If you give this binding an ID and then override it using a keymap, then it'll replace both keys.

Can I use the Keymap to disable a binding?

This is probably better handled using separate app-specific config defined by the app developer. In other words, allow the binding to still fire, but add a check at the top of the action_ handler to no-op.

[willmcgugan]

Make it so.

[Yurii-huang]

In the past, when binding keys, I used to reassign them by inheriting classes.

There seem to be some issues with binding,
Binding is assigned the property of classdata (unchangeable) during construction, and I encountered some difficulties when trying to translate the description.

Later on, I implemented this function through drawing about Footer.

I am a dictionary translation obtained at runtime (after the textual program selects the current language), which means it cannot be constructed before the class. My expectation is that the description can be obtained through the return value of a method. Is this possible？

[darrenburns]

We don't offer a way of updating the descriptions in keys in the footer at runtime at the moment.

You may be able to override the Screen.active_bindings property to apply a translation to the active bindings before returning them.

[Yurii-huang]

We don't offer a way of updating the descriptions in keys in the footer at runtime at the moment.

You may be able to override the property to apply a translation to the active bindings before returning them.Screen.active_bindings

This should be very important, in some cross regional programs, the key description should be able to be changed. If it cannot be supported, it means that the Footer component is not working at all. Need to override

[darrenburns]

As I said, it likely can be changed if you override the active_bindings method.

[Yurii-huang]

Perhaps the version is too low, 0.43.2. I couldn't find active-bindings, so I had to rewrite Footer