Merge pull request #1417 from Textualize/key-refactor

keys refactor

Author: willmcgugan

CHANGELOG.md

@@ -5,6 +5,7 @@ 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/).
 
+
 ## [0.8.0] - Unreleased
 
 ### Fixed
@@ -18,10 +19,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Added `textual.actions.SkipAction` exception which can be raised from an action to allow parents to process bindings.
 - Added `textual keys` preview.
+- Added ability to bind to a character in addition to key name. i.e. you can bind to "." or "full_stop".
+- Added TextLog.shrink attribute to allow renderable to reduce in size to fit width.
 
 ### Changed
 
-- Moved Ctrl+C, tab, and shift+tab to App BINDINGS
+- Deprecated `PRIORITY_BINDINGS` class variable.
+- Renamed `char` to `character` on Key event.
+- Renamed `key_name` to `name` on Key event.
 - Queries/`walk_children` no longer includes self in results by default https://github.com/Textualize/textual/pull/1416
 
 ## [0.7.0] - 2022-12-17

docs/guide/actions.md

@@ -90,6 +90,8 @@ Textual will run actions bound to keys. The following example adds key [bindings
 
 If you run this example, you can change the background by pressing keys in addition to clicking links.
 
+See the previous section on [input](./input.md#bindings) for more information on bindings.
+
 ## Namespaces
 
 Textual will look for action methods in the class where they are defined (App, Screen, or Widget). If we were to create a [custom widget](./widgets.md#custom-widgets) it can have its own set of actions.
@@ -124,37 +126,9 @@ In the previous example if you wanted a link to set the background on the app ra
 
 Textual supports the following builtin actions which are defined on the app.
 
-
-### Bell
-
-::: textual.app.App.action_bell
-    options:
-        show_root_heading: false
-
-### Push screen
-
-::: textual.app.App.action_push_screen
-
-
-### Pop screen
-
-::: textual.app.App.action_pop_screen
-
-
-### Screenshot
-
-::: textual.app.App.action_screenshot
-
-
-### Switch screen
-
-::: textual.app.App.action_switch_screen
-
-
-### Toggle_dark
-
-::: textual.app.App.action_toggle_dark
-
-### Quit
-
-::: textual.app.App.action_quit
+- [action_bell][textual.app.App.action_bell]
+- [action_push_screen][textual.app.App.action_push_screen]
+- [action_pop_screen][textual.app.App.action_pop_screen]
+- [action_switch_screen][textual.app.App.action_switch_screen]
+- [action_screenshot][textual.app.App.action_screenshot]
+- [action_toggle_dark][textual.app.App.action_toggle_dark]

docs/guide/input.md

@@ -10,7 +10,7 @@ This chapter will discuss how to make your app respond to input in the form of k
 
 ## Keyboard input
 
-The most fundamental way to receive input is via [Key](./events/key) events. Let's write an app to show key events as you type.
+The most fundamental way to receive input is via [Key][textual.events.Key] events which are sent to your app when the user presses a key. Let's write an app to show key events as you type.
 
 === "key01.py"
 
@@ -23,25 +23,52 @@ The most fundamental way to receive input is via [Key](./events/key) events. Let
     ```{.textual path="docs/examples/guide/input/key01.py", press="T,e,x,t,u,a,l,!,_"}
     ```
 
-Note the key event handler on the app which logs all key events. If you press any key it will show up on the screen.
+When you press a key, the app will receive the event and write it to a [TextLog](../widgets/text_log.md) widget. Try pressing a few keys to see what happens.
 
-### Attributes
+!!! tip
 
-There are two main attributes on a key event. The `key` attribute is the _name_ of the key which may be a single character, or a longer identifier. Textual ensures that the `key` attribute could always be used in a method name.
+    For a more feature feature rich version of this example, run `textual keys` from the command line.
 
-Key events also contain a `char` attribute which contains a single character if it is printable, or ``None`` if it is not printable (like a function key which has no corresponding character).
+### Key Event
 
-To illustrate the difference between `key` and `char`, try `key01.py` with the space key. You should see something like the following:
+The key event contains the following attributes which your app can use to know how to respond.
 
-```{.textual path="docs/examples/guide/input/key01.py", press="space,_"}
+#### key
 
-```
+The `key` attribute is a string which identifies the key that was pressed. The value of `key` will be a single character for letters and numbers, or a longer identifier for other keys.
+
+Some keys may be combined with the ++shift++ key. In the case of letters, this will result in a capital letter as you might expect. For non-printable keys, the `key` attribute will be prefixed with `shift+`. For example, ++shift+home++ will produce an event with `key="shift+home"`.
+
+Many keys can also be combined with ++ctrl++ which will prefix the key with `ctrl+`. For instance, ++ctrl+p++ will produce an event with `key="ctrl+p"`.
+
+!!! warning
+
+    Not all keys combinations are supported in terminals and some keys may be intercepted by your OS. If in doubt, run `textual keys` from the command line.
+
+#### character
+
+If the key has an associated printable character, then `character` will contain a string with a single Unicode character. If there is no printable character for the key (such as for function keys) then `character` will be `None`.
+
+For example the ++p++ key will produce `character="p"` but ++f2++ will produce `character=None`.
+
+#### name
+
+The `name` attribute is similar to `key` but, unlike `key`, is guaranteed to be valid within a Python function name. Textual derives `name` from the `key` attribute by lower casing it and replacing `+` with `_`. Upper case letters are prefixed with `upper_` to distinguish them from lower case names.
+
+For example, ++ctrl+p++ produces `name="ctrl_p"` and ++shift+p++ produces `name="upper_p"`.
+
+#### is_printable
+
+The `is_printable` attribute is a boolean which indicates if the key would typically result in something that could be used in an input widget. If `is_printable` is `False` then the key is a control code or function key that you wouldn't expect to produce anything in an input.
+
+#### aliases
+
+Some keys or combinations of keys can produce the same event. For instance, the ++tab++ key is indistinguishable from ++ctrl+i++ in the terminal. For such keys, Textual events will contain a list of the possible keys that may have produced this event. In the case of ++tab++, the `aliases` attribute will contain `["tab", "ctrl+i"]`
 
-Note that the `key` attribute contains the word "space" while the `char` attribute contains a literal space.
 
 ### Key methods
 
-Textual offers a convenient way of handling specific keys. If you create a method beginning with `key_` followed by the name of a key, then that method will be called in response to the key.
+Textual offers a convenient way of handling specific keys. If you create a method beginning with `key_` followed by the key name (the event's `name` attribute), then that method will be called in response to the key press.
 
 Let's add a key method to the example code.
 
@@ -127,24 +154,28 @@ Note how the footer displays bindings and makes them clickable.
     Multiple keys can be bound to a single action by comma-separating them.
     For example, `("r,t", "add_bar('red')", "Add Red")` means both ++r++ and ++t++ are bound to `add_bar('red')`.
 
+### Binding class
 
-!!! note
-
-    Ordinarily a binding on a focused widget has precedence over the same key binding at a higher level. However, bindings at the `App` or `Screen` level always have priority.
+The tuple of three strings may be enough for simple bindings, but you can also replace the tuple with a [Binding][textual.binding.Binding] instance which exposes a few more options.
 
-    The priority of a single binding can be controlled with the `priority` parameter of a `Binding` instance. Set it to `True` to give it priority, or `False` to not.
+### Priority bindings
 
-    The default priority of all bindings on a class can be controlled with the `PRIORITY_BINDINGS` class variable. Set it to `True` or `False` to set the default priroty for all `BINDINGS`.
+Individual bindings may be marked as a *priority*, which means they will be checked prior to the bindings of the focused widget. This feature is often used to create hot-keys on the app or screen. Such bindings can not be disabled by binding the same key on a widget.
 
-### Binding class
+You can create priority key bindings by setting `priority=True` on the Binding object. Textual uses this feature to add a default binding for ++ctrl+c++ so there is always a way to exit the app. Here's the bindings from the App base class. Note the first binding is set as a priority:
 
-The tuple of three strings may be enough for simple bindings, but you can also replace the tuple with a [Binding][textual.binding.Binding] instance which exposes a few more options.
+```python
+    BINDINGS = [
+        Binding("ctrl+c", "quit", "Quit", show=False, priority=True),
+        Binding("tab", "focus_next", "Focus Next", show=False),
+        Binding("shift+tab", "focus_previous", "Focus Previous", show=False),
+    ]
+```
 
-### Why use bindings?
+### Show bindings
 
-Bindings are particularly useful for configurable hot-keys. Bindings can also be inspected in widgets such as [Footer](../widgets/footer.md).
+The [footer](../widgets/footer.md) widget can inspect bindings to display available keys. If you don't want a binding to display in the footer you can set `show=False`. The default bindings on App do this so that the standard ++ctrl+c++, ++tab++ and ++shift+tab++ bindings don't typically appear in the footer.
 
-In a future version of Textual it will also be possible to specify bindings in a configuration file, which will allow users to override app bindings.
 
 ## Mouse Input
 

src/textual/app.py

@@ -232,8 +232,6 @@ class App(Generic[ReturnType], DOMNode):
     }
     """
 
-    PRIORITY_BINDINGS = True
-
     SCREENS: dict[str, Screen | Callable[[], Screen]] = {}
     _BASE_PATH: str | None = None
     CSS_PATH: CSSPathType = None
@@ -242,10 +240,8 @@ class App(Generic[ReturnType], DOMNode):
 
     BINDINGS = [
         Binding("ctrl+c", "quit", "Quit", show=False, priority=True),
-        Binding("tab", "focus_next", "Focus Next", show=False, priority=False),
-        Binding(
-            "shift+tab", "focus_previous", "Focus Previous", show=False, priority=False
-        ),
+        Binding("tab", "focus_next", "Focus Next", show=False),
+        Binding("shift+tab", "focus_previous", "Focus Previous", show=False),
     ]
 
     title: Reactive[str] = Reactive("")

src/textual/binding.py

@@ -5,6 +5,7 @@
 
 import rich.repr
 
+from textual.keys import _character_to_key
 from textual._typing import TypeAlias
 
 BindingType: TypeAlias = "Binding | tuple[str, str, str]"
@@ -18,6 +19,10 @@ class NoBinding(Exception):
     """A binding was not found."""
 
 
+class InvalidBinding(Exception):
+    """Binding key is in an invalid format."""
+
+
 @dataclass(frozen=True)
 class Binding:
     """The configuration of a key binding."""
@@ -32,8 +37,8 @@ class Binding:
     """bool: Show the action in Footer, or False to hide."""
     key_display: str | None = None
     """str | None: How the key should be shown in footer."""
-    priority: bool | None = None
-    """bool | None: Is this a priority binding, checked form app down to focused widget?"""
+    priority: bool = False
+    """bool: Enable priority binding for this key."""
 
 
 @rich.repr.auto
@@ -43,13 +48,11 @@ class Bindings:
     def __init__(
         self,
         bindings: Iterable[BindingType] | None = None,
-        default_priority: bool | None = None,
     ) -> None:
         """Initialise a collection of bindings.
 
         Args:
             bindings (Iterable[BindingType] | None, optional): An optional set of initial bindings.
-            default_priority (bool | None, optional): The default priority of the bindings.
 
         Note:
             The iterable of bindings can contain either a `Binding`
@@ -71,17 +74,20 @@ def make_bindings(bindings: Iterable[BindingType]) -> Iterable[Binding]:
                 # 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.strip(),
+                        key=key,
                         action=binding.action,
                         description=binding.description,
                         show=binding.show,
                         key_display=binding.key_display,
-                        priority=(
-                            default_priority
-                            if binding.priority is None
-                            else binding.priority
-                        ),
+                        priority=binding.priority,
                     )
 
         self.keys: MutableMapping[str, Binding] = (

src/textual/cli/cli.py

@@ -127,7 +127,7 @@ def colors():
 
 @run.command("keys")
 def keys():
-    """Show key events"""
+    """Show key events."""
     from textual.cli.previews import keys
 
     keys.app.run()

src/textual/cli/previews/keys.py

@@ -9,7 +9,7 @@
 INSTRUCTIONS = """\
 Press some keys!    
 
-Because we want to display all the keys, Ctrl+C won't work for this example. Use the button below to quit.\
+Because we want to display all the keys, ctrl+C won't quit this example. Use the Quit button below to exit the app.\
 """
 
 

src/textual/dom.py

@@ -92,9 +92,6 @@ class DOMNode(MessagePump):
     # Virtual DOM nodes
     COMPONENT_CLASSES: ClassVar[set[str]] = set()
 
-    # Should the content of BINDINGS be treated as priority bindings?
-    PRIORITY_BINDINGS: ClassVar[bool] = False
-
     # Mapping of key bindings
     BINDINGS: ClassVar[list[BindingType]] = []
 
@@ -233,13 +230,13 @@ def _merge_bindings(cls) -> Bindings:
 
         for base in reversed(cls.__mro__):
             if issubclass(base, DOMNode):
-                # See if the current class wants to set the bindings as
-                # priority bindings. If it doesn't have that property on the
-                # class, go with what we saw last.
-                priority = base.__dict__.get("PRIORITY_BINDINGS", priority)
                 if not base._inherit_bindings:
                     bindings.clear()
-                bindings.append(Bindings(base.__dict__.get("BINDINGS", []), priority))
+                bindings.append(
+                    Bindings(
+                        base.__dict__.get("BINDINGS", []),
+                    )
+                )
         keys = {}
         for bindings_ in bindings:
             keys.update(bindings_.keys)