Don't repaint if mouse handler returns NotImplemented.

Author: jonathanslenders

Diff for: prompt_toolkit/key_binding/bindings/mouse.py

@@ -1,4 +1,4 @@
-from typing import FrozenSet
+from typing import TYPE_CHECKING, FrozenSet
 
 from prompt_toolkit.data_structures import Point
 from prompt_toolkit.key_binding.key_processor import KeyPress, KeyPressEvent
@@ -13,6 +13,9 @@
 
 from ..key_bindings import KeyBindings
 
+if TYPE_CHECKING:
+    from prompt_toolkit.key_binding.key_bindings import NotImplementedOrNone
+
 __all__ = [
     "load_mouse_bindings",
 ]
@@ -185,7 +188,7 @@ def load_mouse_bindings() -> KeyBindings:
     key_bindings = KeyBindings()
 
     @key_bindings.add(Keys.Vt100MouseEvent)
-    def _(event: E) -> None:
+    def _(event: E) -> "NotImplementedOrNone":
         """
         Handling of incoming mouse event.
         """
@@ -235,7 +238,7 @@ def _(event: E) -> None:
                         mouse_modifiers,
                     ) = xterm_sgr_mouse_events[mouse_event, m]
                 except KeyError:
-                    return
+                    return NotImplemented
 
             else:
                 # Some other terminals, like urxvt, Hyper terminal, ...
@@ -259,11 +262,16 @@ def _(event: E) -> None:
             try:
                 y -= event.app.renderer.rows_above_layout
             except HeightIsUnknownError:
-                return
+                return NotImplemented
 
             # Call the mouse handler from the renderer.
+
+            # Note: This can return `NotImplemented` if no mouse handler was
+            #       found for this position, or if no repainting needs to
+            #       happen. this way, we avoid excessive repaints during mouse
+            #       movements.
             handler = event.app.renderer.mouse_handlers.mouse_handlers[y][x]
-            handler(
+            return handler(
                 MouseEvent(
                     position=Point(x=x, y=y),
                     event_type=mouse_event_type,
@@ -272,6 +280,8 @@ def _(event: E) -> None:
                 )
             )
 
+        return NotImplemented
+
     @key_bindings.add(Keys.ScrollUp)
     def _scroll_up(event: E) -> None:
         """
@@ -289,7 +299,7 @@ def _scroll_down(event: E) -> None:
         event.key_processor.feed(KeyPress(Keys.Down), first=True)
 
     @key_bindings.add(Keys.WindowsMouseEvent)
-    def _mouse(event: E) -> None:
+    def _mouse(event: E) -> "NotImplementedOrNone":
         """
         Handling of mouse events for Windows.
         """
@@ -317,8 +327,10 @@ def _mouse(event: E) -> None:
             y -= rows_above_cursor
 
             # Call the mouse event handler.
+            # (Can return `NotImplemented`.)
             handler = event.app.renderer.mouse_handlers.mouse_handlers[y][x]
-            handler(
+
+            return handler(
                 MouseEvent(
                     position=Point(x=x, y=y),
                     event_type=event_type,
@@ -327,4 +339,8 @@ def _mouse(event: E) -> None:
                 )
             )
 
+        # No mouse handler found. Return `NotImplemented` so that we don't
+        # invalidate the UI.
+        return NotImplemented
+
     return key_bindings

Diff for: prompt_toolkit/key_binding/key_bindings.py

@@ -35,6 +35,7 @@ def my_key_binding(event):
     kb.add(Keys.A, my_key_binding)
 """
 from abc import ABCMeta, abstractmethod, abstractproperty
+from inspect import isawaitable
 from typing import (
     TYPE_CHECKING,
     Awaitable,
@@ -53,12 +54,27 @@ def my_key_binding(event):
 from prompt_toolkit.filters import FilterOrBool, Never, to_filter
 from prompt_toolkit.keys import KEY_ALIASES, Keys
 
-# Avoid circular imports.
 if TYPE_CHECKING:
+    # Avoid circular imports.
     from .key_processor import KeyPressEvent
 
+    # The only two return values for a mouse hander (and key bindings) are
+    # `None` and `NotImplemented`. For the type checker it's best to annotate
+    # this as `object`. (The consumer never expects a more specific instance:
+    # checking for NotImplemented can be done using `is NotImplemented`.)
+    NotImplementedOrNone = object
+    # Other non-working options are:
+    # * Optional[Literal[NotImplemented]]
+    #      --> Doesn't work, Literal can't take an Any.
+    # * None
+    #      --> Doesn't work. We can't assign the result of a function that
+    #          returns `None` to a variable.
+    # * Any
+    #      --> Works, but too broad.
+
 
 __all__ = [
+    "NotImplementedOrNone",
     "Binding",
     "KeyBindingsBase",
     "KeyBindings",
@@ -68,7 +84,13 @@ def my_key_binding(event):
     "GlobalOnlyKeyBindings",
 ]
 
-KeyHandlerCallable = Callable[["KeyPressEvent"], Union[None, Awaitable[None]]]
+# Key bindings can be regular functions or coroutines.
+# In both cases, if they return `NotImplemented`, the UI won't be invalidated.
+# This is mainly used in case of mouse move events, to prevent excessive
+# repainting during mouse move events.
+KeyHandlerCallable = Callable[
+    ["KeyPressEvent"], Union["NotImplementedOrNone", Awaitable["NotImplementedOrNone"]]
+]
 
 
 class Binding:
@@ -102,8 +124,18 @@ def call(self, event: "KeyPressEvent") -> None:
         result = self.handler(event)
 
         # If the handler is a coroutine, create an asyncio task.
-        if result is not None:
-            event.app.create_background_task(result)
+        if isawaitable(result):
+            awaitable = cast(Awaitable["NotImplementedOrNone"], result)
+
+            async def bg_task() -> None:
+                result = await awaitable
+                if result != NotImplemented:
+                    event.app.invalidate()
+
+            event.app.create_background_task(bg_task())
+
+        elif result != NotImplemented:
+            event.app.invalidate()
 
     def __repr__(self) -> str:
         return "%s(keys=%r, handler=%r)" % (

Diff for: prompt_toolkit/key_binding/key_processor.py

@@ -255,12 +255,9 @@ def get_next() -> KeyPress:
             else:
                 return self.input_queue.popleft()
 
-        keys_processed = False
         is_flush = False
 
         while not_empty():
-            keys_processed = True
-
             # Process next key.
             key_press = get_next()
 
@@ -277,16 +274,11 @@ def get_next() -> KeyPress:
                 # an exception was raised) restart the processor for next time.
                 self.reset()
                 self.empty_queue()
-                app.invalidate()
                 raise
 
             if not is_flush and not is_cpr:
                 self.after_key_press.fire()
 
-        if keys_processed:
-            # Invalidate user interface.
-            app.invalidate()
-
         # Skip timeout if the last key was flush.
         if not is_flush:
             self._start_timeout()

Diff for: prompt_toolkit/layout/containers.py

@@ -61,7 +61,8 @@
 if TYPE_CHECKING:
     from typing_extensions import Protocol, TypeGuard
 
-    NotImplementedOrNone = object
+    from prompt_toolkit.key_binding.key_bindings import NotImplementedOrNone
+
 
 __all__ = [
     "AnyContainer",
@@ -1829,13 +1830,16 @@ def _write_to_screen_at_index(
         self.render_info = render_info
 
         # Set mouse handlers.
-        def mouse_handler(mouse_event: MouseEvent) -> None:
-            """Wrapper around the mouse_handler of the `UIControl` that turns
-            screen coordinates into line coordinates."""
+        def mouse_handler(mouse_event: MouseEvent) -> "NotImplementedOrNone":
+            """
+            Wrapper around the mouse_handler of the `UIControl` that turns
+            screen coordinates into line coordinates.
+            Returns `NotImplemented` if no UI invalidation should be done.
+            """
             # Don't handle mouse events outside of the current modal part of
             # the UI.
             if self not in get_app().layout.walk_through_modal_area():
-                return
+                return NotImplemented
 
             # Find row/col position first.
             yx_to_rowcol = {v: k for k, v in rowcol_to_yx.items()}
@@ -1882,7 +1886,9 @@ def mouse_handler(mouse_event: MouseEvent) -> None:
 
             # If it returns NotImplemented, handle it here.
             if result == NotImplemented:
-                self._mouse_handler(mouse_event)
+                result = self._mouse_handler(mouse_event)
+
+            return result
 
         mouse_handlers.set_mouse_handler_for_range(
             x_min=write_position.xpos + sum(left_margin_widths),
@@ -2552,15 +2558,22 @@ def do_scroll(
             ),
         )
 
-    def _mouse_handler(self, mouse_event: MouseEvent) -> None:
+    def _mouse_handler(self, mouse_event: MouseEvent) -> "NotImplementedOrNone":
         """
         Mouse handler. Called when the UI control doesn't handle this
         particular event.
+
+        Return `NotImplemented` if nothing was done as a consequence of this
+        key binding (no UI invalidate required in that case).
         """
         if mouse_event.event_type == MouseEventType.SCROLL_DOWN:
             self._scroll_down()
+            return None
         elif mouse_event.event_type == MouseEventType.SCROLL_UP:
             self._scroll_up()
+            return None
+
+        return NotImplemented
 
     def _scroll_down(self) -> None:
         "Scroll window down."

Diff for: prompt_toolkit/layout/controls.py

@@ -32,12 +32,7 @@
     split_lines,
 )
 from prompt_toolkit.lexers import Lexer, SimpleLexer
-from prompt_toolkit.mouse_events import (
-    MouseButton,
-    MouseEvent,
-    MouseEventType,
-    MouseModifier,
-)
+from prompt_toolkit.mouse_events import MouseButton, MouseEvent, MouseEventType
 from prompt_toolkit.search import SearchState
 from prompt_toolkit.selection import SelectionType
 from prompt_toolkit.utils import get_cwidth
@@ -53,23 +48,12 @@
 )
 
 if TYPE_CHECKING:
-    from prompt_toolkit.key_binding.key_bindings import KeyBindingsBase
+    from prompt_toolkit.key_binding.key_bindings import (
+        KeyBindingsBase,
+        NotImplementedOrNone,
+    )
     from prompt_toolkit.utils import Event
 
-    # The only two return values for a mouse hander are `None` and
-    # `NotImplemented`. For the type checker it's best to annotate this as
-    # `object`. (The consumer never expects a more specific instance: checking
-    # for NotImplemented can be done using `is NotImplemented`.)
-    NotImplementedOrNone = object
-    # Other non-working options are:
-    # * Optional[Literal[NotImplemented]]
-    #      --> Doesn't work, Literal can't take an Any.
-    # * None
-    #      --> Doesn't work. We can't assign the result of a function that
-    #          returns `None` to a variable.
-    # * Any
-    #      --> Works, but too broad.
-
 
 __all__ = [
     "BufferControl",

Diff for: prompt_toolkit/layout/menus.py

@@ -40,9 +40,11 @@
 from .margins import ScrollbarMargin
 
 if TYPE_CHECKING:
-    from prompt_toolkit.key_binding.key_bindings import KeyBindings
+    from prompt_toolkit.key_binding.key_bindings import (
+        KeyBindings,
+        NotImplementedOrNone,
+    )
 
-    NotImplementedOrNone = object
 
 __all__ = [
     "CompletionsMenu",

Diff for: prompt_toolkit/layout/mouse_handlers.py

@@ -1,15 +1,18 @@
 from collections import defaultdict
-from itertools import product
-from typing import Callable, DefaultDict, Tuple
+from typing import TYPE_CHECKING, Callable, DefaultDict
 
 from prompt_toolkit.mouse_events import MouseEvent
 
+if TYPE_CHECKING:
+    from prompt_toolkit.key_binding.key_bindings import NotImplementedOrNone
+
 __all__ = [
     "MouseHandler",
     "MouseHandlers",
 ]
 
-MouseHandler = Callable[[MouseEvent], None]
+
+MouseHandler = Callable[[MouseEvent], "NotImplementedOrNone"]
 
 
 class MouseHandlers:
@@ -18,10 +21,11 @@ class MouseHandlers:
     """
 
     def __init__(self) -> None:
-        def dummy_callback(mouse_event: MouseEvent) -> None:
+        def dummy_callback(mouse_event: MouseEvent) -> "NotImplementedOrNone":
             """
             :param mouse_event: `MouseEvent` instance.
             """
+            return NotImplemented
 
         # NOTE: Previously, the data structure was a dictionary mapping (x,y)
         # to the handlers. This however would be more inefficient when copying
@@ -38,7 +42,7 @@ def set_mouse_handler_for_range(
         x_max: int,
         y_min: int,
         y_max: int,
-        handler: Callable[[MouseEvent], None],
+        handler: Callable[[MouseEvent], "NotImplementedOrNone"],
     ) -> None:
         """
         Set mouse handler for a region.

Diff for: prompt_toolkit/widgets/menus.py

@@ -16,7 +16,7 @@
     Window,
 )
 from prompt_toolkit.layout.controls import FormattedTextControl
-from prompt_toolkit.mouse_events import MouseButton, MouseEvent, MouseEventType
+from prompt_toolkit.mouse_events import MouseEvent, MouseEventType
 from prompt_toolkit.utils import get_cwidth
 from prompt_toolkit.widgets import Shadow