ENH: Add API to manage view state in custom Axes.

QuLogic · QuLogic · commit eb80fe5ad5cd · 2015-08-06T14:43:12.000-04:00
Custom Axes may require additional information than simply the x/y
limits to describe the view. This API will allow the navigation buttons
on the toolbar to function correctly with such Axes.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3132,6 +3132,40 @@ def set_navigate_mode(self, b):
         """
         self._navigate_mode = b
 
+    def _get_view(self):
+        """
+        Save information required to reproduce the current view.
+
+        Called before a view is changed, such as during a pan or zoom
+        initiated by the user. You may return any information you deem
+        necessary to describe the view.
+
+        .. note::
+
+            Intended to be overridden by new projection types, but if not, the
+            default implementation saves the view limits. You *must* implement
+            :meth:`_set_view` if you implement this method.
+        """
+        xmin, xmax = self.get_xlim()
+        ymin, ymax = self.get_ylim()
+        return (xmin, xmax, ymin, ymax)
+
+    def _set_view(self, view):
+        """
+        Apply a previously saved view.
+
+        Called when restoring a view, such as with the navigation buttons.
+
+        .. note::
+
+            Intended to be overridden by new projection types, but if not, the
+            default implementation restores the view limits. You *must*
+            implement :meth:`_get_view` if you implement this method.
+        """
+        xmin, xmax, ymin, ymax = view
+        self.set_xlim((xmin, xmax))
+        self.set_ylim((ymin, ymax))
+
     def start_pan(self, x, y, button):
         """
         Called when a pan operation has started.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2949,17 +2949,15 @@ def _switch_off_zoom_mode(self, event):
 
     def push_current(self):
         """push the current view limits and position onto the stack"""
-        lims = []
+        views = []
         pos = []
         for a in self.canvas.figure.get_axes():
-            xmin, xmax = a.get_xlim()
-            ymin, ymax = a.get_ylim()
-            lims.append((xmin, xmax, ymin, ymax))
+            views.append(a._get_view())
             # Store both the original and modified positions
             pos.append((
                 a.get_position(True).frozen(),
                 a.get_position().frozen()))
-        self._views.push(lims)
+        self._views.push(views)
         self._positions.push(pos)
         self.set_history_buttons()
 
@@ -3164,16 +3162,14 @@ def _update_view(self):
         position stack for each axes
         """
 
-        lims = self._views()
-        if lims is None:
+        views = self._views()
+        if views is None:
             return
         pos = self._positions()
         if pos is None:
             return
         for i, a in enumerate(self.canvas.figure.get_axes()):
-            xmin, xmax, ymin, ymax = lims[i]
-            a.set_xlim((xmin, xmax))
-            a.set_ylim((ymin, ymax))
+            a._set_view(views[i])
             # Restore both the original and modified positions
             a.set_position(pos[i][0], 'original')
             a.set_position(pos[i][1], 'active')
diff --git a/lib/matplotlib/backend_tools.py b/lib/matplotlib/backend_tools.py
@@ -466,16 +466,14 @@ def update_view(self):
         position stack for each axes
         """
 
-        lims = self.views[self.figure]()
-        if lims is None:
+        views = self.views[self.figure]()
+        if views is None:
             return
         pos = self.positions[self.figure]()
         if pos is None:
             return
         for i, a in enumerate(self.figure.get_axes()):
-            xmin, xmax, ymin, ymax = lims[i]
-            a.set_xlim((xmin, xmax))
-            a.set_ylim((ymin, ymax))
+            a._set_view(views[i])
             # Restore both the original and modified positions
             a.set_position(pos[i][0], 'original')
             a.set_position(pos[i][1], 'active')
@@ -485,17 +483,15 @@ def update_view(self):
     def push_current(self):
         """push the current view limits and position onto the stack"""
 
-        lims = []
+        views = []
         pos = []
         for a in self.figure.get_axes():
-            xmin, xmax = a.get_xlim()
-            ymin, ymax = a.get_ylim()
-            lims.append((xmin, xmax, ymin, ymax))
+            views.append(a._get_view())
             # Store both the original and modified positions
             pos.append((
                 a.get_position(True).frozen(),
                 a.get_position().frozen()))
-        self.views[self.figure].push(lims)
+        self.views[self.figure].push(views)
         self.positions[self.figure].push(pos)
 
     def refresh_locators(self):
