Simplify connection of the default key_press and button_press handlers.

anntzer · anntzer · commit 3e66047f5149 · 2020-04-13T00:37:39.000+02:00
It likely doesn't make much sense to call `key_press_handler` or
`button_press_handler` with `canvas != event.canvas` or
`toolbar != event.canvas.toolbar` (the default Toolbar constructor sets
itself as this attribute on the canvas), so we can just make these
parameters optional and fill them in from `event`.  This means that
connecting these handlers is now just
`canvas.mpl_connect("key_press_event", key_press_handler)`, rather than
having to create an intermediate function to adjust the signature (see
change in embedding_in_tk_sgskip.py).

`canvas` and `toolbar` could probably even be deleted, but I'm not sure
the API change is actually worth it -- plus there may be someone
somewhere who actually has a use case for `toolbar` not matching
`event.canvas.toolbar`...
diff --git a/doc/users/next_whats_new/2020-04-13-AL.rst b/doc/users/next_whats_new/2020-04-13-AL.rst
@@ -0,0 +1,7 @@
+`.backend_bases.key_press_handler` and `.backend_bases.button_press_handler` simplifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These event handlers can now be directly connected to a canvas with
+``canvas.mpl_connect("key_press_event", key_press_handler)`` and
+``canvas.mpl_connect("button_press_event", button_press_handler)``, rather than
+having to write wrapper functions that fill in the (now optional) *canvas* and
+*toolbar* parameters.
diff --git a/examples/user_interfaces/embedding_in_tk_sgskip.py b/examples/user_interfaces/embedding_in_tk_sgskip.py
@@ -31,12 +31,9 @@
 toolbar.update()
 
 
-def on_key_press(event):
-    print("you pressed {}".format(event.key))
-    key_press_handler(event, canvas, toolbar)
-
-
-canvas.mpl_connect("key_press_event", on_key_press)
+canvas.mpl_connect(
+    "key_press_event", lambda event: print(f"you pressed {event.key}"))
+canvas.mpl_connect("key_press_event", key_press_handler)
 
 button = tkinter.Button(master=root, text="Quit", command=root.quit)
 
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2306,24 +2306,32 @@ def stop_event_loop(self):
         self._looping = False
 
 
-def key_press_handler(event, canvas, toolbar=None):
+def key_press_handler(event, canvas=None, toolbar=None):
     """
     Implement the default Matplotlib key bindings for the canvas and toolbar
     described at :ref:`key-event-handling`.
 
     Parameters
     ----------
     event : `KeyEvent`
-        a key press/release event
-    canvas : `FigureCanvasBase`
-        the backend-specific canvas instance
-    toolbar : `NavigationToolbar2`
-        the navigation cursor toolbar
+        A key press/release event.
+    canvas : `FigureCanvasBase`, optional, default: ``event.canvas``
+        The backend-specific canvas instance.  This parameter is kept for
+        back-compatibility, but, if set, should always be equal to
+        ``event.canvas``.
+    toolbar : `NavigationToolbar2`, optional, default: ``event.canvas.toolbar``
+        The navigation cursor toolbar.  This parameter is kept for
+        back-compatibility, but, if set, should always be equal to
+        ``event.canvas.toolbar``.
     """
     # these bindings happen whether you are over an axes or not
 
     if event.key is None:
         return
+    if canvas is None:
+        canvas = event.canvas
+    if toolbar is None:
+        toolbar = canvas.toolbar
 
     # Load key-mappings from rcParams.
     fullscreen_keys = rcParams['keymap.fullscreen']
@@ -2483,10 +2491,17 @@ def _get_uniform_gridstate(ticks):
                     a.set_navigate(i == n)
 
 
-def button_press_handler(event, canvas, toolbar=None):
+def button_press_handler(event, canvas=None, toolbar=None):
     """
     The default Matplotlib button actions for extra mouse buttons.
+
+    Parameters are as for `key_press_handler`, except that *event* is a
+    `MouseEvent`.
     """
+    if canvas is None:
+        canvas = event.canvas
+    if toolbar is None:
+        toolbar = canvas.toolbar
     if toolbar is not None:
         button_name = str(MouseButton(event.button))
         if button_name in rcParams['keymap.back']:
@@ -2610,12 +2625,12 @@ def key_press(self, event):
         :ref:`key-event-handling`.
         """
         if rcParams['toolbar'] != 'toolmanager':
-            key_press_handler(event, self.canvas, self.canvas.toolbar)
+            key_press_handler(event)
 
     def button_press(self, event):
         """The default Matplotlib button actions for extra mouse buttons."""
         if rcParams['toolbar'] != 'toolmanager':
-            button_press_handler(event, self.canvas, self.canvas.toolbar)
+            button_press_handler(event)
 
     def get_window_title(self):
         """
