From f6689b89eb5ab5c0ceb84b7455eb0d5887709127 Mon Sep 17 00:00:00 2001
From: JamesWrigley <james@puiterwijk.org>
Date: Sun, 17 Apr 2022 17:09:50 +0200
Subject: [PATCH] Implement panhandler.enable() and panhandler.disable()

Useful when you want to manually enable/disable the handler.
---
 docs/examples/zoom-factory.ipynb | 17 +++++++++
 mpl_interactions/generic.py      | 65 +++++++++++++++++++++++++++++---
 2 files changed, 76 insertions(+), 6 deletions(-)

diff --git a/docs/examples/zoom-factory.ipynb b/docs/examples/zoom-factory.ipynb
index 74a6706..6ad56c3 100644
--- a/docs/examples/zoom-factory.ipynb
+++ b/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": {
diff --git a/mpl_interactions/generic.py b/mpl_interactions/generic.py
index 1a6b505..e27014e 100644
--- a/mpl_interactions/generic.py
+++ b/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 = []