Merge pull request #243 from JamesWrigley/panhandler_disconnect

Implement panhandler.__call__() to disconnect a panhandler

docs/examples/zoom-factory.ipynb

@@ -92,6 +92,23 @@
    "source": [
     "![](../_static/images/zoom-and-pan.gif)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "It's also possible to manually enable and disable the `panhandler`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pan_handler.disable()\n",
+    "pan_handler.enable()"
+   ]
   }
  ],
  "metadata": {

mpl_interactions/generic.py

@@ -306,18 +306,71 @@ class panhandler:
     """
     Enable panning a plot with any mouse button.
 
-    button determines which button will be used (default right click)
-    Left: 1
-    Middle: 2
-    Right: 3
+    .. code-block:: python
+
+       handler = panhandler(my_figure)
+
+       # Let it be disabled and garbage collected
+       handler = None
+
+    Parameters
+    ----------
+    button : int
+        Determines which button will be used (default right click).
+        Left: 1
+        Middle: 2
+        Right: 3
     """
 
     def __init__(self, fig, button=3):
         self.fig = fig
         self._id_drag = None
         self.button = button
-        self.fig.canvas.mpl_connect("button_press_event", self.press)
-        self.fig.canvas.mpl_connect("button_release_event", self.release)
+        self._id_press = None
+        self._id_release = None
+
+        self.enable()
+
+    @property
+    def enabled(self) -> bool:
+        """
+        Status of the panhandler, whether it's enabled or disabled.
+        """
+        return self._id_press is not None and self._id_release is not None
+
+    def enable(self):
+        """
+        Enable the panhandler. It should not be necessary to call this function
+        unless it's used after a call to :meth:`panhandler.disable`.
+
+        Raises
+        ------
+        RuntimeError
+            If the panhandler is already enabled.
+        """
+        if self.enabled:
+            raise RuntimeError("The panhandler is already enabled")
+
+        self._id_press = self.fig.canvas.mpl_connect("button_press_event", self.press)
+        self._id_release = self.fig.canvas.mpl_connect("button_release_event", self.release)
+
+    def disable(self):
+        """
+        Disable the panhandler.
+
+        Raises
+        ------
+        RuntimeError
+            If the panhandler is already disabled.
+        """
+        if not self.enabled:
+            raise RuntimeError("The panhandler is already disabled")
+
+        self.fig.canvas.mpl_disconnect(self._id_press)
+        self.fig.canvas.mpl_disconnect(self._id_release)
+
+        self._id_press = None
+        self._id_release = None
 
     def _cancel_action(self):
         self._xypress = []