Make it easier to improve UI event metadata.

Currently, UI events (MouseEvent, KeyEvent, etc.) are generated by
letting the GUI-specific backends massage the native event objects into
a list of args/kwargs and then call
`FigureCanvasBase.motion_notify_event`/`.key_press_event`/etc.  This
makes it a bit tricky to improve the metadata on the events, because one
needs to change the signature on both the `FigureCanvasBase` method and
the event class.  Moreover, the `motion_notify_event`/etc. methods are
directly bound as event handlers in the gtk3 and tk backends, and thus
have incompatible signatures there.

Instead, the native GUI handlers can directly construct the relevant
event objects and trigger the events themselves; a new `Event._process`
helper method makes this even shorter (and allows to keep factoring some
common functionality e.g. for tracking the last pressed button or key).

As an example, this PR also updates figure_leave_event to always
correctly set the event location based on the *current* cursor position,
instead of the last triggered location event (which may be outdated);
this can now easily be done on a backend-by-backend basis, instead of
coordinating the change with FigureCanvasBase.figure_leave_event.

This also exposed another (minor) issue, in that resize events
often trigger *two* calls to draw_idle -- one in the GUI-specific
handler, and one in FigureCanvasBase.draw_idle (now moved to
ResizeEvent._process, but should perhaps instead be a callback
autoconnected to "resize_event") -- could probably be fixed later.

Author: anntzer

doc/api/next_api_changes/deprecations/16931-AL.rst

@@ -0,0 +1,11 @@
+Event handlers
+~~~~~~~~~~~~~~
+The ``draw_event``, ``resize_event``, ``close_event``, ``key_press_event``,
+``key_release_event``, ``pick_event``, ``scroll_event``,
+``button_press_event``, ``button_release_event``, ``motion_notify_event``,
+``enter_notify_event`` and ``leave_notify_event`` methods of `.FigureCanvasBase`
+are deprecated.  They had inconsistent signatures across backends, and made it
+difficult to improve event metadata.
+
+In order to trigger an event on a canvas, directly construct an `.Event` object
+of the correct class and call ``canvas.callbacks.process(event.name, event)``.

lib/matplotlib/artist.py

@@ -498,6 +498,7 @@ def pick(self, mouseevent):
         --------
         set_picker, get_picker, pickable
         """
+        from .backend_bases import PickEvent  # Circular import.
         # Pick self
         if self.pickable():
             picker = self.get_picker()
@@ -506,7 +507,8 @@ def pick(self, mouseevent):
             else:
                 inside, prop = self.contains(mouseevent)
             if inside:
-                self.figure.canvas.pick_event(mouseevent, self, **prop)
+                PickEvent("pick_event", self.figure.canvas,
+                          mouseevent, self, **prop)._process()
 
         # Pick children
         for a in self.get_children():

lib/matplotlib/backend_bases.py

@@ -1220,11 +1220,16 @@ class Event:
     guiEvent
         The GUI event that triggered the Matplotlib event.
     """
+
     def __init__(self, name, canvas, guiEvent=None):
         self.name = name
         self.canvas = canvas
         self.guiEvent = guiEvent
 
+    def _process(self):
+        """Generate an event with name ``self.name`` on ``self.canvas``."""
+        self.canvas.callbacks.process(self.name, self)
+
 
 class DrawEvent(Event):
     """
@@ -1267,14 +1272,28 @@ class ResizeEvent(Event):
     height : int
         Height of the canvas in pixels.
     """
+
     def __init__(self, name, canvas):
         super().__init__(name, canvas)
         self.width, self.height = canvas.get_width_height()
 
+    def _process(self):
+        super()._process()
+        self.canvas.draw_idle()
+
 
 class CloseEvent(Event):
     """An event triggered by a figure being closed."""
 
+    def _process(self):
+        try:
+            super()._process()
+        except (AttributeError, TypeError):
+            pass
+            # Suppress AttributeError/TypeError that occur when the python
+            # session is being killed.  It may be that a better solution would
+            # be a mechanism to disconnect all callbacks upon shutdown.
+
 
 class LocationEvent(Event):
     """
@@ -1294,7 +1313,7 @@ class LocationEvent(Event):
         is not over an Axes.
     """
 
-    lastevent = None  # the last event that was triggered before this one
+    lastevent = None  # The last event processed so far.
 
     def __init__(self, name, canvas, x, y, guiEvent=None):
         super().__init__(name, canvas, guiEvent=guiEvent)
@@ -1308,7 +1327,6 @@ def __init__(self, name, canvas, x, y, guiEvent=None):
 
         if x is None or y is None:
             # cannot check if event was in Axes if no (x, y) info
-            self._update_enter_leave()
             return
 
         if self.canvas.mouse_grabber is None:
@@ -1326,33 +1344,21 @@ def __init__(self, name, canvas, x, y, guiEvent=None):
                 self.xdata = xdata
                 self.ydata = ydata
 
-        self._update_enter_leave()
-
-    def _update_enter_leave(self):
-        """Process the figure/axes enter leave events."""
-        if LocationEvent.lastevent is not None:
-            last = LocationEvent.lastevent
-            if last.inaxes != self.inaxes:
-                # process Axes enter/leave events
+    def _process(self):
+        last = LocationEvent.lastevent
+        last_axes = last.inaxes if last is not None else None
+        if last_axes != self.inaxes:
+            if last_axes is not None:
                 try:
-                    if last.inaxes is not None:
-                        last.canvas.callbacks.process('axes_leave_event', last)
+                    last.canvas.callbacks.process("axes_leave_event", last)
                 except Exception:
+                    # The last canvas may already have been torn down.
                     pass
-                    # See ticket 2901582.
-                    # I think this is a valid exception to the rule
-                    # against catching all exceptions; if anything goes
-                    # wrong, we simply want to move on and process the
-                    # current event.
-                if self.inaxes is not None:
-                    self.canvas.callbacks.process('axes_enter_event', self)
-
-        else:
-            # process a figure enter event
             if self.inaxes is not None:
-                self.canvas.callbacks.process('axes_enter_event', self)
-
-        LocationEvent.lastevent = self
+                self.canvas.callbacks.process("axes_enter_event", self)
+        LocationEvent.lastevent = (
+            None if self.name == "figure_leave_event" else self)
+        super()._process()
 
 
 class MouseButton(IntEnum):
@@ -1375,11 +1381,15 @@ class MouseEvent(LocationEvent):
     ----------
     button : None or `MouseButton` or {'up', 'down'}
         The button pressed. 'up' and 'down' are used for scroll events.
+
         Note that LEFT and RIGHT actually refer to the "primary" and
         "secondary" buttons, i.e. if the user inverts their left and right
         buttons ("left-handed setting") then the LEFT button will be the one
         physically on the right.
 
+        If this is unset, *name* is "scroll_event", and *step* is nonzero, then
+        this will be set to "up" or "down" depending on the sign of *step*.
+
     key : None or str
         The key pressed when the mouse event triggered, e.g. 'shift'.
         See `KeyEvent`.
@@ -1413,6 +1423,11 @@ def __init__(self, name, canvas, x, y, button=None, key=None,
                  step=0, dblclick=False, guiEvent=None):
         if button in MouseButton.__members__.values():
             button = MouseButton(button)
+        if name == "scroll_event" and button is None:
+            if step > 0:
+                button = "up"
+            elif step < 0:
+                button = "down"
         self.button = button
         self.key = key
         self.step = step
@@ -1422,6 +1437,17 @@ def __init__(self, name, canvas, x, y, button=None, key=None,
         # 'axes_enter_event', which requires a fully initialized event.
         super().__init__(name, canvas, x, y, guiEvent=guiEvent)
 
+    def _process(self):
+        if self.name == "button_press_event":
+            self.canvas._button = self.button
+        elif self.name == "button_release_event":
+            self.canvas._button = None
+        elif self.name == "motion_notify_event" and self.button is None:
+            self.button = self.canvas._button
+        if self.key is None:
+            self.key = self.canvas._key
+        super()._process()
+
     def __str__(self):
         return (f"{self.name}: "
                 f"xy=({self.x}, {self.y}) xydata=({self.xdata}, {self.ydata}) "
@@ -1467,8 +1493,11 @@ def on_pick(event):
 
         cid = fig.canvas.mpl_connect('pick_event', on_pick)
     """
+
     def __init__(self, name, canvas, mouseevent, artist,
                  guiEvent=None, **kwargs):
+        if guiEvent is None:
+            guiEvent = mouseevent.guiEvent
         super().__init__(name, canvas, guiEvent)
         self.mouseevent = mouseevent
         self.artist = artist
@@ -1506,11 +1535,19 @@ def on_key(event):
 
         cid = fig.canvas.mpl_connect('key_press_event', on_key)
     """
+
     def __init__(self, name, canvas, key, x=0, y=0, guiEvent=None):
         self.key = key
         # super-init deferred to the end: callback errors if called before
         super().__init__(name, canvas, x, y, guiEvent=guiEvent)
 
+    def _process(self):
+        if self.name == "key_press_event":
+            self.canvas._key = self.key
+        elif self.name == "key_release_event":
+            self.canvas._key = None
+        super()._process()
+
 
 def _get_renderer(figure, print_method=None):
     """
@@ -1720,12 +1757,16 @@ def resize(self, w, h):
             _api.warn_deprecated("3.6", name="resize", obj_type="method",
                                  alternative="FigureManagerBase.resize")
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('draw_event', DrawEvent(...))"))
     def draw_event(self, renderer):
         """Pass a `DrawEvent` to all functions connected to ``draw_event``."""
         s = 'draw_event'
         event = DrawEvent(s, self, renderer)
         self.callbacks.process(s, event)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('resize_event', ResizeEvent(...))"))
     def resize_event(self):
         """
         Pass a `ResizeEvent` to all functions connected to ``resize_event``.
@@ -1735,6 +1776,8 @@ def resize_event(self):
         self.callbacks.process(s, event)
         self.draw_idle()
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('close_event', CloseEvent(...))"))
     def close_event(self, guiEvent=None):
         """
         Pass a `CloseEvent` to all functions connected to ``close_event``.
@@ -1751,6 +1794,8 @@ def close_event(self, guiEvent=None):
             # AttributeError occurs on OSX with qt4agg upon exiting
             # with an open window; 'callbacks' attribute no longer exists.
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('key_press_event', KeyEvent(...))"))
     def key_press_event(self, key, guiEvent=None):
         """
         Pass a `KeyEvent` to all functions connected to ``key_press_event``.
@@ -1761,6 +1806,8 @@ def key_press_event(self, key, guiEvent=None):
             s, self, key, self._lastx, self._lasty, guiEvent=guiEvent)
         self.callbacks.process(s, event)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('key_release_event', KeyEvent(...))"))
     def key_release_event(self, key, guiEvent=None):
         """
         Pass a `KeyEvent` to all functions connected to ``key_release_event``.
@@ -1771,6 +1818,8 @@ def key_release_event(self, key, guiEvent=None):
         self.callbacks.process(s, event)
         self._key = None
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('pick_event', PickEvent(...))"))
     def pick_event(self, mouseevent, artist, **kwargs):
         """
         Callback processing for pick events.
@@ -1787,6 +1836,8 @@ def pick_event(self, mouseevent, artist, **kwargs):
                           **kwargs)
         self.callbacks.process(s, event)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('scroll_event', MouseEvent(...))"))
     def scroll_event(self, x, y, step, guiEvent=None):
         """
         Callback processing for scroll events.
@@ -1807,6 +1858,8 @@ def scroll_event(self, x, y, step, guiEvent=None):
                                 step=step, guiEvent=guiEvent)
         self.callbacks.process(s, mouseevent)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('button_press_event', MouseEvent(...))"))
     def button_press_event(self, x, y, button, dblclick=False, guiEvent=None):
         """
         Callback processing for mouse button press events.
@@ -1824,6 +1877,8 @@ def button_press_event(self, x, y, button, dblclick=False, guiEvent=None):
                                 dblclick=dblclick, guiEvent=guiEvent)
         self.callbacks.process(s, mouseevent)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('button_release_event', MouseEvent(...))"))
     def button_release_event(self, x, y, button, guiEvent=None):
         """
         Callback processing for mouse button release events.
@@ -1848,6 +1903,9 @@ def button_release_event(self, x, y, button, guiEvent=None):
         self.callbacks.process(s, event)
         self._button = None
 
+    # Also remove _lastx, _lasty when this goes away.
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('motion_notify_event', MouseEvent(...))"))
     def motion_notify_event(self, x, y, guiEvent=None):
         """
         Callback processing for mouse movement events.
@@ -1873,6 +1931,8 @@ def motion_notify_event(self, x, y, guiEvent=None):
                            guiEvent=guiEvent)
         self.callbacks.process(s, event)
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('leave_notify_event', LocationEvent(...))"))
     def leave_notify_event(self, guiEvent=None):
         """
         Callback processing for the mouse cursor leaving the canvas.
@@ -1889,6 +1949,8 @@ def leave_notify_event(self, guiEvent=None):
         LocationEvent.lastevent = None
         self._lastx, self._lasty = None, None
 
+    @_api.deprecated("3.6", alternative=(
+        "callbacks.process('enter_notify_event', LocationEvent(...))"))
     def enter_notify_event(self, guiEvent=None, xy=None):
         """
         Callback processing for the mouse cursor entering the canvas.