Merge branch 'main' of github.com:Textualize/textual into binding-des…

…criptions

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

docs/FAQ.md

@@ -58,7 +58,7 @@ Some terminal emulators have a translucent background feature which allows the d
 This feature is unlikely to work with Textual, as the translucency effect requires the use of ANSI background colors, which Textual doesn't use.
 Textual uses 16.7 million colors where available which enables consistent colors across all platforms and additional effects which aren't possible with ANSI colors.
 
-For more information on ANSI colors in Textual, see [Why no Ansi Themes?](#why-doesnt-textual-support-ansi-themes).
+For more information on ANSI colors in Textual, see [Why no ANSI Themes?](#why-doesnt-textual-support-ansi-themes).
 
 ---
 
@@ -68,7 +68,7 @@ For more information on ANSI colors in Textual, see [Why no Ansi Themes?](#why-d
 !!! tip
 
     See [*How To Center Things*](https://textual.textualize.io/how-to/center-things/) in the
-    Textual documentation for a more comprensive answer to this question.
+    Textual documentation for a more comprehensive answer to this question.
 
 To center a widget within a container use
 [`align`](https://textual.textualize.io/styles/align/). But remember that
@@ -130,7 +130,7 @@ If you want them more like this:
 +---------------+
 ```
 
-the best approach is to wrap each widget in a [`Center`
+The best approach is to wrap each widget in a [`Center`
 container](https://textual.textualize.io/api/containers/#textual.containers.Center)
 that individually centers it. For example:
 
@@ -267,10 +267,10 @@ work in different environments you can try them out with `textual keys`.
 
 ---
 
-<a name="why-doesn't-textual-look-good-on-macos"></a>
+<a name="why-doesnt-textual-look-good-on-macos"></a>
 ## Why doesn't Textual look good on macOS?
 
-You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particuarily when it comes to box characters.
+You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particularly when it comes to box characters.
 For instance, you may find it displays misaligned blocks and lines like this:
 
 <img width="1042" alt="Screenshot 2023-06-19 at 10 43 02" src="https://github.com/Textualize/textual/assets/554369/e61f3876-3dd1-4ac8-b380-22922c89c7d6">
@@ -305,7 +305,7 @@ We recommend any of the following terminals:
 
 ---
 
-<a name="why-doesn't-textual-support-ansi-themes"></a>
+<a name="why-doesnt-textual-support-ansi-themes"></a>
 ## Why doesn't Textual support ANSI themes?
 
 Textual will not generate escape sequences for the 16 themeable *ANSI* colors.
@@ -319,22 +319,22 @@ Textual has a design system which guarantees apps will be readable on all platfo
 
 There is currently a light and dark version of the design system, but more are planned. It will also be possible for users to customize the source colors on a per-app or per-system basis. This means that in the future you will be able to modify the core colors to blend in with your chosen terminal theme.
 
-!!! Changed in 0.80.0
+!!! tip "Changed in version 0.80.0"
 
-  Textual added an `ansi_color` boolean to App. If you set this to `True`, then Textual will
-  not attempt to convert ansi colors. Note that you will lose transparency effects if you enable
-  this setting.
+    Textual added an `ansi_color` boolean to App. If you set this to `True`, then Textual will not attempt to convert ANSI colors. Note that you will lose transparency effects if you enable this setting.
 
 ---
 
-<a name="why-doesn't-the-`datatable`-scroll-programmatically"></a>
+<a name="why-doesnt-the-datatable-scroll-programmatically"></a>
 ## Why doesn't the `DataTable` scroll programmatically?
 
 If scrolling in your `DataTable` is _apparently_ broken, it may be because your `DataTable` is using the default value of `height: auto`.
 This means that the table will be sized to fit its rows without scrolling, which may cause the *container* (typically the screen) to scroll.
 If you would like the table itself to scroll, set the height to something other than `auto`, like `100%`.
 
-**NOTE:** As of Textual v0.31.0 the `max-height` of a `DataTable` is set to `100%`, this will mean that the above is no longer the default experience.
+!!! note
+
+    As of Textual v0.31.0 the `max-height` of a `DataTable` is set to `100%`, this will mean that the above is no longer the default experience.
 
 ---
 

docs/api/index.md

@@ -1,5 +1,5 @@
 # API
 
-This is a API-level reference to the Textual API. Click the links to your left (or in the burger menu) to open a reference for each module.
+This is a API-level reference to the Textual API. Click the links to your left (or in the :octicons-three-bars-16: menu) to open a reference for each module.
 
 If you are new to Textual, you may want to read the [tutorial](./../tutorial.md) or [guide](../guide/index.md) first.

docs/api/renderables.md

@@ -2,7 +2,7 @@
 title: "textual.renderables"
 ---
 
-A collection of Rich renderables which may be returned from a widget's `render()` method.
+A collection of Rich renderables which may be returned from a widget's [`render()`][textual.widget.Widget.render] method.
 
 ::: textual.renderables.bar
 ::: textual.renderables.blank

docs/events/index.md

@@ -2,4 +2,4 @@
 
 A reference to Textual [events](../guide/events.md).
 
-See the links to the left of the page, or in the hamburger menu (three horizontal bars, top left).
+See the links to the left of the page, or click :octicons-three-bars-16: (top left).

docs/help.md

@@ -4,12 +4,12 @@ If you need help with any aspect of Textual, let us know! We would be happy to h
 
 ## Bugs and feature requests
 
-Report bugs via GitHub on the Textual [issues](https://github.com/Textualize/textual/issues) page. You can also post feature requests via GitHub issues, but see the [roadmap](./roadmap.md) first.
+Report bugs via GitHub on the Textual [issues](https://github.com/Textualize/textual/issues) page. You can also post feature requests via GitHub issues, but see the [Roadmap](./roadmap.md) first.
 
 ## Help with using Textual
 
 You can seek help with using Textual [in the discussion area on GitHub](https://github.com/Textualize/textual/discussions).
 
 ## Discord Server
 
-For more realtime feedback or chat, join our discord server to connect with the [Textual community](https://discord.gg/Enf6Z3qhVr).
+For more realtime feedback or chat, join our Discord server to connect with the [Textual community](https://discord.gg/Enf6Z3qhVr).

docs/index.md

@@ -138,7 +138,7 @@ Build sophisticated user interfaces with a simple Python API. Run your apps in t
 === "stopwatch.tcss"
 
     ```css
-    --8<-- "examples/calculator.tcss"
+    --8<-- "docs/examples/tutorial/stopwatch.tcss"
     ```
 
 

questions/align-center-middle.question.md

@@ -12,7 +12,7 @@ alt_titles:
 !!! tip
 
     See [*How To Center Things*](https://textual.textualize.io/how-to/center-things/) in the
-    Textual documentation for a more comprensive answer to this question.
+    Textual documentation for a more comprehensive answer to this question.
 
 To center a widget within a container use
 [`align`](https://textual.textualize.io/styles/align/). But remember that
@@ -74,7 +74,7 @@ If you want them more like this:
 +---------------+
 ```
 
-the best approach is to wrap each widget in a [`Center`
+The best approach is to wrap each widget in a [`Center`
 container](https://textual.textualize.io/api/containers/#textual.containers.Center)
 that individually centers it. For example:
 

questions/datatable-doesnt-scroll.question.md

@@ -9,4 +9,6 @@ If scrolling in your `DataTable` is _apparently_ broken, it may be because your
 This means that the table will be sized to fit its rows without scrolling, which may cause the *container* (typically the screen) to scroll.
 If you would like the table itself to scroll, set the height to something other than `auto`, like `100%`.
 
-**NOTE:** As of Textual v0.31.0 the `max-height` of a `DataTable` is set to `100%`, this will mean that the above is no longer the default experience.
+!!! note
+
+    As of Textual v0.31.0 the `max-height` of a `DataTable` is set to `100%`, this will mean that the above is no longer the default experience.

questions/transparent-background.question.md

@@ -11,4 +11,4 @@ Some terminal emulators have a translucent background feature which allows the d
 This feature is unlikely to work with Textual, as the translucency effect requires the use of ANSI background colors, which Textual doesn't use.
 Textual uses 16.7 million colors where available which enables consistent colors across all platforms and additional effects which aren't possible with ANSI colors.
 
-For more information on ANSI colors in Textual, see [Why no Ansi Themes?](#why-doesnt-textual-support-ansi-themes).
+For more information on ANSI colors in Textual, see [Why no ANSI Themes?](#why-doesnt-textual-support-ansi-themes).

questions/why-looks-bad-on-macos.question.md

@@ -10,7 +10,7 @@ alt_titles:
   - "macOS terminal"
 ---
 
-You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particuarily when it comes to box characters.
+You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particularly when it comes to box characters.
 For instance, you may find it displays misaligned blocks and lines like this:
 
 <img width="1042" alt="Screenshot 2023-06-19 at 10 43 02" src="https://github.com/Textualize/textual/assets/554369/e61f3876-3dd1-4ac8-b380-22922c89c7d6">

questions/why-no-ansi-themes.question.md

@@ -16,8 +16,6 @@ Textual has a design system which guarantees apps will be readable on all platfo
 
 There is currently a light and dark version of the design system, but more are planned. It will also be possible for users to customize the source colors on a per-app or per-system basis. This means that in the future you will be able to modify the core colors to blend in with your chosen terminal theme.
 
-!!! Changed in 0.80.0
+!!! tip "Changed in version 0.80.0"
 
-  Textual added an `ansi_color` boolean to App. If you set this to `True`, then Textual will
-  not attempt to convert ansi colors. Note that you will lose transparency effects if you enable
-  this setting.
+    Textual added an `ansi_color` boolean to App. If you set this to `True`, then Textual will not attempt to convert ANSI colors. Note that you will lose transparency effects if you enable this setting.

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
@@ -3829,7 +3876,7 @@ async def action_pop_screen(self) -> None:
         self.pop_screen()
 
     async def action_switch_mode(self, mode: str) -> None:
-        """An [action](/guide/actions) that switches to the given mode.."""
+        """An [action](/guide/actions) that switches to the given mode."""
         self.switch_mode(mode)
 
     async def action_back(self) -> None: