Keymaps (#5038)

Author: darrenburns

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+
+### Added
+
+- Added support for keymaps (user configurable key bindings) https://github.com/Textualize/textual/pull/5038
+
 ## [0.81.0] - 2024-09-25
 
 ### Added

src/textual/app.py

@@ -91,7 +91,7 @@
 from textual.actions import ActionParseResult, SkipAction
 from textual.await_complete import AwaitComplete
 from textual.await_remove import AwaitRemove
-from textual.binding import Binding, BindingsMap, BindingType
+from textual.binding import Binding, BindingsMap, BindingType, Keymap
 from textual.command import CommandPalette, Provider
 from textual.css.errors import StylesheetError
 from textual.css.query import NoMatches
@@ -659,6 +659,8 @@ def __init__(
 
         self._registry: WeakSet[DOMNode] = WeakSet()
 
+        self._keymap: Keymap = {}
+
         # Sensitivity on X is double the sensitivity on Y to account for
         # cells being twice as tall as wide
         self.scroll_sensitivity_x: float = 4.0
@@ -754,8 +756,8 @@ def __init__(
         happens.
         """
 
-        # Size of previous inline update
         self._previous_inline_height: int | None = None
+        """Size of previous inline update."""
 
         if self.ENABLE_COMMAND_PALETTE:
             for _key, binding in self._bindings:
@@ -3422,6 +3424,51 @@ async def _check_bindings(self, key: str, priority: bool = False) -> bool:
                         return True
         return False
 
+    def set_keymap(self, keymap: Keymap) -> None:
+        """Set the keymap, a mapping of binding IDs to key strings.
+
+        Bindings in the keymap are used to override default key bindings,
+        i.e. those defined in `BINDINGS` class variables.
+
+        Bindings with IDs that are present in the keymap will have
+        their key string replaced with the value from the keymap.
+
+        Args:
+            keymap: A mapping of binding IDs to key strings.
+        """
+        self._keymap = keymap
+
+    def update_keymap(self, keymap: Keymap) -> None:
+        """Update the App's keymap, merging with `keymap`.
+
+        If a Binding ID exists in both the App's keymap and the `keymap`
+        argument, the `keymap` argument takes precedence.
+
+        Args:
+            keymap: A mapping of binding IDs to key strings.
+        """
+        self._keymap = {**self._keymap, **keymap}
+
+    def handle_bindings_clash(
+        self, clashed_bindings: set[Binding], node: DOMNode
+    ) -> None:
+        """Handle a clash between bindings.
+
+        Bindings clashes are likely due to users setting conflicting
+        keys via their keymap.
+
+        This method is intended to be overridden by subclasses.
+
+        Textual will call this each time a clash is encountered -
+        which may be on each keypress if a clashing widget is focused
+        or is in the bindings chain.
+
+        Args:
+            clashed_bindings: The bindings that are clashing.
+            node: The node that has the clashing bindings.
+        """
+        pass
+
     async def on_event(self, event: events.Event) -> None:
         # Handle input events that haven't been forwarded
         # If the event has been forwarded it may have bubbled up back to the App

src/textual/binding.py

@@ -7,8 +7,9 @@
 
 from __future__ import annotations
 
+import dataclasses
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Iterable, Iterator, NamedTuple
+from typing import TYPE_CHECKING, Iterable, Iterator, Mapping, NamedTuple
 
 import rich.repr
 
@@ -20,6 +21,22 @@
     from textual.dom import DOMNode
 
 BindingType: TypeAlias = "Binding | tuple[str, str] | tuple[str, str, str]"
+"""The possible types of a binding found in the `BINDINGS` class variable."""
+
+BindingIDString: TypeAlias = str
+"""The ID of a Binding defined somewhere in the application.
+
+Corresponds to the `id` parameter of the `Binding` class.
+"""
+
+KeyString: TypeAlias = str
+"""A string that represents a key binding.
+
+For example, "x", "ctrl+i", "ctrl+shift+a", "ctrl+j,space,x", etc.
+"""
+
+Keymap = Mapping[BindingIDString, KeyString]
+"""A mapping of binding IDs to key strings, used for overriding default key bindings."""
 
 
 class BindingError(Exception):
@@ -47,12 +64,24 @@ class Binding:
     show: bool = True
     """Show the action in Footer, or False to hide."""
     key_display: str | None = None
-    """How the key should be shown in footer."""
+    """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: bool = False
     """Enable priority binding for this key."""
     tooltip: str = ""
     """Optional tooltip to show in footer."""
 
+    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.
+    """
+
     def parse_key(self) -> tuple[list[str], str]:
         """Parse a key in to a list of modifiers, and the actual key.
 
@@ -62,6 +91,65 @@ def parse_key(self) -> tuple[list[str], str]:
         *modifiers, key = self.key.split("+")
         return modifiers, key
 
+    def with_key(self, key: str, key_display: str | None = None) -> Binding:
+        """Return a new binding with the key and key_display set to the specified values.
+
+        Args:
+            key: The new key to set.
+            key_display: The new key display to set.
+
+        Returns:
+            A new binding with the key set to the specified value.
+        """
+        return dataclasses.replace(self, key=key, key_display=key_display)
+
+    @classmethod
+    def make_bindings(cls, bindings: Iterable[BindingType]) -> Iterable[Binding]:
+        """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.
+
+        Args:
+            bindings: An iterable of BindingType.
+
+        Returns:
+            An iterable of Binding.
+        """
+        bindings = list(bindings)
+        for binding in bindings:
+            # If it's a tuple of length 3, convert into a Binding first
+            if isinstance(binding, tuple):
+                if len(binding) not in (2, 3):
+                    raise BindingError(
+                        f"BINDINGS must contain a tuple of two or three strings, not {binding!r}"
+                    )
+                # `binding` is a tuple of 2 or 3 values at this point
+                binding = Binding(*binding)  # type: ignore[reportArgumentType]
+
+            # At this point we have a Binding instance, but the key may
+            # be a list of keys, so now we unroll that single Binding
+            # into a (potential) collection of Binding instances.
+            for key in binding.key.split(","):
+                key = key.strip()
+                if not key:
+                    raise InvalidBinding(
+                        f"Can not bind empty string in {binding.key!r}"
+                    )
+                if len(key) == 1:
+                    key = _character_to_key(key)
+
+                yield Binding(
+                    key=key,
+                    action=binding.action,
+                    description=binding.description,
+                    show=bool(binding.description and binding.show),
+                    key_display=binding.key_display,
+                    priority=binding.priority,
+                    tooltip=binding.tooltip,
+                    id=binding.id,
+                )
+
 
 class ActiveBinding(NamedTuple):
     """Information about an active binding (returned from [active_bindings][textual.screen.Screen.active_bindings])."""
@@ -95,41 +183,10 @@ def __init__(
             properties of a `Binding`.
         """
 
-        def make_bindings(bindings: Iterable[BindingType]) -> Iterable[Binding]:
-            bindings = list(bindings)
-            for binding in bindings:
-                # If it's a tuple of length 3, convert into a Binding first
-                if isinstance(binding, tuple):
-                    if len(binding) not in (2, 3):
-                        raise BindingError(
-                            f"BINDINGS must contain a tuple of two or three strings, not {binding!r}"
-                        )
-                    # `binding` is a tuple of 2 or 3 values at this point
-                    binding = Binding(*binding)  # type: ignore[reportArgumentType]
-
-                # At this point we have a Binding instance, but the key may
-                # be a list of keys, so now we unroll that single Binding
-                # into a (potential) collection of Binding instances.
-                for key in binding.key.split(","):
-                    key = key.strip()
-                    if not key:
-                        raise InvalidBinding(
-                            f"Can not bind empty string in {binding.key!r}"
-                        )
-                    if len(key) == 1:
-                        key = _character_to_key(key)
-                    yield Binding(
-                        key=key,
-                        action=binding.action,
-                        description=binding.description,
-                        show=bool(binding.description and binding.show),
-                        key_display=binding.key_display,
-                        priority=binding.priority,
-                        tooltip=binding.tooltip,
-                    )
-
         self.key_to_bindings: dict[str, list[Binding]] = {}
-        for binding in make_bindings(bindings or {}):
+        """Mapping of key (e.g. "ctrl+a") to list of bindings for that key."""
+
+        for binding in Binding.make_bindings(bindings or {}):
             self.key_to_bindings.setdefault(binding.key, []).append(binding)
 
     def _add_binding(self, binding: Binding) -> None:
@@ -193,6 +250,71 @@ def merge(cls, bindings: Iterable[BindingsMap]) -> BindingsMap:
                 keys.setdefault(key, []).extend(key_bindings)
         return BindingsMap.from_keys(keys)
 
+    def apply_keymap(self, keymap: Keymap) -> KeymapApplyResult:
+        """Replace bindings for keys that are present in `keymap`.
+
+        Preserves existing bindings for keys that are not in `keymap`.
+
+        Args:
+            keymap: A keymap to overlay.
+
+        Returns:
+            KeymapApplyResult: The result of applying the keymap, including any clashed bindings.
+        """
+        clashed_bindings: set[Binding] = set()
+        new_bindings: dict[str, list[Binding]] = {}
+
+        key_to_bindings = list(self.key_to_bindings.items())
+        for key, bindings in key_to_bindings:
+            for binding in bindings:
+                binding_id = binding.id
+                if binding_id is None:
+                    # Bindings without an ID are irrelevant when applying a keymap
+                    continue
+
+                # If the keymap has an override for this binding ID
+                if keymap_key_string := keymap.get(binding_id):
+                    keymap_keys = keymap_key_string.split(",")
+
+                    # Remove the old binding
+                    for key, key_bindings in key_to_bindings:
+                        key = key.strip()
+                        if any(binding.id == binding_id for binding in key_bindings):
+                            if key in self.key_to_bindings:
+                                del self.key_to_bindings[key]
+
+                    for keymap_key in keymap_keys:
+                        if (
+                            keymap_key in self.key_to_bindings
+                            or keymap_key in new_bindings
+                        ):
+                            # The key is already mapped either by default or by the keymap,
+                            # so there's a clash unless the existing binding is being rebound
+                            # to a different key.
+                            clashing_bindings = self.key_to_bindings.get(
+                                keymap_key, []
+                            ) + new_bindings.get(keymap_key, [])
+                            for clashed_binding in clashing_bindings:
+                                # If the existing binding is not being rebound, it's a clash
+                                if not (
+                                    clashed_binding.id
+                                    and keymap.get(clashed_binding.id)
+                                    != clashed_binding.key
+                                ):
+                                    clashed_bindings.add(clashed_binding)
+
+                            if keymap_key in self.key_to_bindings:
+                                del self.key_to_bindings[keymap_key]
+
+                    for keymap_key in keymap_keys:
+                        new_bindings.setdefault(keymap_key, []).append(
+                            binding.with_key(key=keymap_key, key_display=None)
+                        )
+
+        # Update the key_to_bindings with the new bindings
+        self.key_to_bindings.update(new_bindings)
+        return KeymapApplyResult(clashed_bindings)
+
     @property
     def shown_keys(self) -> list[Binding]:
         """A list of bindings for shown keys."""
@@ -252,3 +374,10 @@ def get_bindings_for_key(self, key: str) -> list[Binding]:
             return self.key_to_bindings[key]
         except KeyError:
             raise NoBinding(f"No binding for {key}") from None
+
+
+class KeymapApplyResult(NamedTuple):
+    """The result of applying a keymap."""
+
+    clashed_bindings: set[Binding]
+    """A list of bindings that were clashed and replaced by the keymap."""

src/textual/dom.py

@@ -218,7 +218,7 @@ def __init__(
         self._has_hover_style: bool = False
         self._has_focus_within: bool = False
         self._reactive_connect: (
-            dict[str, tuple[MessagePump, Reactive | object]] | None
+            dict[str, tuple[MessagePump, Reactive[object] | object]] | None
         ) = None
         self._pruning = False
         self._query_one_cache: LRUCache[QueryOneCacheKey, DOMNode] = LRUCache(1024)
@@ -620,12 +620,13 @@ def _merge_bindings(cls) -> BindingsMap:
                         base.__dict__.get("BINDINGS", []),
                     )
                 )
+
         keys: dict[str, list[Binding]] = {}
         for bindings_ in bindings:
             for key, key_bindings in bindings_.key_to_bindings.items():
                 keys[key] = key_bindings
 
-        new_bindings = BindingsMap().from_keys(keys)
+        new_bindings = BindingsMap.from_keys(keys)
         return new_bindings
 
     def _post_register(self, app: App) -> None: