Merge pull request matplotlib#29993 from anntzer/undoevent

Trigger events via standard callbacks in widget testing.

Author: QuLogic

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

@@ -0,0 +1,4 @@
+``testing.widgets.mock_event`` and ``testing.widgets.do_event``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... are deprecated.  Directly construct Event objects (typically `.MouseEvent`
+or `.KeyEvent`) and pass them to ``canvas.callbacks.process()`` instead.

lib/matplotlib/backend_bases.py

@@ -1413,6 +1413,23 @@ def __init__(self, name, canvas, x, y, button=None, key=None,
         self.step = step
         self.dblclick = dblclick
 
+    @classmethod
+    def _from_ax_coords(cls, name, ax, xy, *args, **kwargs):
+        """
+        Generate a synthetic event at a given axes coordinate.
+
+        This method is intended for creating events during testing.  The event
+        can be emitted by calling its ``_process()`` method.
+
+        args and kwargs are mapped to `.MouseEvent.__init__` parameters,
+        starting with `button`.
+        """
+        x, y = ax.transData.transform(xy)
+        event = cls(name, ax.figure.canvas, x, y, *args, **kwargs)
+        event.inaxes = ax
+        event.xdata, event.ydata = xy  # Force exact xy to avoid fp roundtrip issues.
+        return event
+
     def __str__(self):
         return (f"{self.name}: "
                 f"xy=({self.x}, {self.y}) xydata=({self.xdata}, {self.ydata}) "
@@ -1505,6 +1522,22 @@ def __init__(self, name, canvas, key, x=0, y=0, guiEvent=None):
         super().__init__(name, canvas, x, y, guiEvent=guiEvent)
         self.key = key
 
+    @classmethod
+    def _from_ax_coords(cls, name, ax, xy, key, *args, **kwargs):
+        """
+        Generate a synthetic event at a given axes coordinate.
+
+        This method is intended for creating events during testing.  The event
+        can be emitted by calling its ``_process()`` method.
+        """
+        # Separate from MouseEvent._from_ax_coords instead of being defined in the base
+        # class, due to different parameter order in the constructor signature.
+        x, y = ax.transData.transform(xy)
+        event = cls(name, ax.figure.canvas, key, x, y, *args, **kwargs)
+        event.inaxes = ax
+        event.xdata, event.ydata = xy  # Force exact xy to avoid fp roundtrip issues.
+        return event
+
 
 # Default callback for key events.
 def _key_handler(event):

lib/matplotlib/testing/widgets.py

@@ -8,6 +8,8 @@
 
 from unittest import mock
 
+from matplotlib import _api
+from matplotlib.backend_bases import MouseEvent, KeyEvent
 import matplotlib.pyplot as plt
 
 
@@ -24,6 +26,7 @@ def noop(*args, **kwargs):
     pass
 
 
+@_api.deprecated("3.11", alternative="MouseEvent or KeyEvent")
 def mock_event(ax, button=1, xdata=0, ydata=0, key=None, step=1):
     r"""
     Create a mock event that can stand in for `.Event` and its subclasses.
@@ -65,6 +68,7 @@ def mock_event(ax, button=1, xdata=0, ydata=0, key=None, step=1):
     return event
 
 
+@_api.deprecated("3.11", alternative="callbacks.process(event)")
 def do_event(tool, etype, button=1, xdata=0, ydata=0, key=None, step=1):
     """
     Trigger an event on the given tool.
@@ -105,15 +109,12 @@ def click_and_drag(tool, start, end, key=None):
          An optional key that is pressed during the whole operation
          (see also `.KeyEvent`).
     """
-    if key is not None:
-        # Press key
-        do_event(tool, 'on_key_press', xdata=start[0], ydata=start[1],
-                 button=1, key=key)
+    ax = tool.ax
+    if key is not None:  # Press key
+        KeyEvent._from_ax_coords("key_press_event", ax, start, key)._process()
     # Click, move, and release mouse
-    do_event(tool, 'press', xdata=start[0], ydata=start[1], button=1)
-    do_event(tool, 'onmove', xdata=end[0], ydata=end[1], button=1)
-    do_event(tool, 'release', xdata=end[0], ydata=end[1], button=1)
-    if key is not None:
-        # Release key
-        do_event(tool, 'on_key_release', xdata=end[0], ydata=end[1],
-                 button=1, key=key)
+    MouseEvent._from_ax_coords("button_press_event", ax, start, 1)._process()
+    MouseEvent._from_ax_coords("motion_notify_event", ax, end, 1)._process()
+    MouseEvent._from_ax_coords("button_release_event", ax, end, 1)._process()
+    if key is not None:  # Release key
+        KeyEvent._from_ax_coords("key_release_event", ax, end, key)._process()