Standardize creation of FigureManager from a given FigureCanvas class.

anntzer · anntzer · commit 10edb9a4c5ec · 2021-03-01T15:50:32.000+01:00
The `new_manager` classmethod may appear to belong more naturally to the
FigureManager class rather than the FigureCanvas class, but putting it
on FigureCanvas has multiple advantages:

- One may want to create managers at times where all one has is a
  FigureCanvas instance, which may not even have a corresponding manager
  (e.g. `subplot_tool`).
- A given FigureManager class can be associated with many different
  FigureCanvas classes (indeed, FigureManagerQT can manage both
  FigureCanvasQTAgg and FigureCanvasQTCairo and also the mplcairo Qt
  canvas classes), whereas we don't have multiple FigureManager classes
  for a given FigureCanvas class.
diff --git a/doc/api/next_api_changes/deprecations/18854-AL.rst b/doc/api/next_api_changes/deprecations/18854-AL.rst
@@ -0,0 +1,7 @@
+``FigureFrameWx`` and subclasses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``FigureFrameWx.get_canvas`` was a helper for the ``FigureFrameWx`` constructor,
+and is now deprecated.  ``FigureFrameWxAgg`` and ``FigureFrameWxCairo`` are
+deprecated in favor of passing the corresponding canvas class as the *canvas_cls*
+kwarg to ``FigureFrameWx``.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -46,12 +46,13 @@
 from matplotlib import (
     _api, backend_tools as tools, cbook, colors, docstring, textpath,
     tight_bbox, transforms, widgets, get_backend, is_interactive, rcParams)
+from matplotlib._enums import JoinStyle, CapStyle
 from matplotlib._pylab_helpers import Gcf
 from matplotlib.backend_managers import ToolManager
 from matplotlib.cbook import _setattr_cm
 from matplotlib.path import Path
 from matplotlib.transforms import Affine2D
-from matplotlib._enums import JoinStyle, CapStyle
+from matplotlib.widgets import SubplotTool
 
 
 _log = logging.getLogger(__name__)
@@ -1762,6 +1763,16 @@ def _fix_ipython_backend2gui(cls):
             if _is_non_interactive_terminal_ipython(ip):
                 ip.enable_gui(backend2gui_rif)
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        """
+        Create a new figure manager for *figure*, using this canvas class.
+
+        Backends should override this method to instantiate the correct figure
+        manager subclass, and perform any additional setup that may be needed.
+        """
+        return FigureManagerBase(cls(figure), num)
+
     @contextmanager
     def _idle_draw_cntx(self):
         self._is_idle_drawing = True
@@ -3308,9 +3319,16 @@ def _update_view(self):
         self.canvas.draw_idle()
 
     def configure_subplots(self, *args):
-        plt = _safe_pyplot_import()
-        self.subplot_tool = plt.subplot_tool(self.canvas.figure)
-        self.subplot_tool.figure.canvas.manager.show()
+        # This import needs to happen here due to circular imports.
+        from matplotlib.figure import Figure
+        with mpl.rc_context({"toolbar": "none"}):  # No navbar for the toolfig.
+            manager = type(self.canvas).new_manager(Figure(figsize=(6, 3)), -1)
+        manager.set_window_title("Subplot configuration tool")
+        tool_fig = manager.canvas.figure
+        tool_fig.subplots_adjust(top=0.9)
+        manager.show()
+        self.subplot_tool = SubplotTool(self.canvas.figure, tool_fig)
+        return self.subplot_tool
 
     def save_figure(self, *args):
         """Save the current figure."""
@@ -3549,9 +3567,7 @@ def new_figure_manager(cls, num, *args, **kwargs):
     @classmethod
     def new_figure_manager_given_figure(cls, num, figure):
         """Create a new figure manager instance for the given figure."""
-        canvas = cls.FigureCanvas(figure)
-        manager = cls.FigureManager(canvas, num)
-        return manager
+        return cls.FigureCanvas.new_manager(figure, num)
 
     @classmethod
     def draw_if_interactive(cls):
diff --git a/lib/matplotlib/backends/_backend_tk.py b/lib/matplotlib/backends/_backend_tk.py
@@ -209,6 +209,35 @@ def filter_destroy(event):
         self._master = master
         self._tkcanvas.focus_set()
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        # docstring inherited
+        with _restore_foreground_window_at_end():
+            if cbook._get_running_interactive_framework() is None:
+                cbook._setup_new_guiapp()
+            window = tk.Tk(className="matplotlib")
+            window.withdraw()
+
+            # Put a Matplotlib icon on the window rather than the default tk
+            # icon.  Tkinter doesn't allow colour icons on linux systems, but
+            # tk>=8.5 has a iconphoto command which we call directly.  See
+            # http://mail.python.org/pipermail/tkinter-discuss/2006-November/000954.html
+            icon_fname = str(cbook._get_data_path(
+                'images/matplotlib_128.ppm'))
+            icon_img = tk.PhotoImage(file=icon_fname, master=window)
+            try:
+                window.iconphoto(False, icon_img)
+            except Exception as exc:
+                # log the failure (due e.g. to Tk version), but carry on
+                _log.info('Could not load matplotlib icon: %s', exc)
+
+            canvas = cls(figure, master=window)
+            manager = FigureManagerTk(canvas, num, window)
+            if mpl.is_interactive():
+                manager.show()
+                canvas.draw_idle()
+            return manager
+
     def resize(self, event):
         width, height = event.width, event.height
         if self._resize_callback is not None:
@@ -859,37 +888,6 @@ def trigger(self, *args):
 class _BackendTk(_Backend):
     FigureManager = FigureManagerTk
 
-    @classmethod
-    def new_figure_manager_given_figure(cls, num, figure):
-        """
-        Create a new figure manager instance for the given figure.
-        """
-        with _restore_foreground_window_at_end():
-            if cbook._get_running_interactive_framework() is None:
-                cbook._setup_new_guiapp()
-            window = tk.Tk(className="matplotlib")
-            window.withdraw()
-
-            # Put a Matplotlib icon on the window rather than the default tk
-            # icon.  Tkinter doesn't allow colour icons on linux systems, but
-            # tk>=8.5 has a iconphoto command which we call directly.  See
-            # http://mail.python.org/pipermail/tkinter-discuss/2006-November/000954.html
-            icon_fname = str(cbook._get_data_path(
-                'images/matplotlib_128.ppm'))
-            icon_img = tk.PhotoImage(file=icon_fname, master=window)
-            try:
-                window.iconphoto(False, icon_img)
-            except Exception as exc:
-                # log the failure (due e.g. to Tk version), but carry on
-                _log.info('Could not load matplotlib icon: %s', exc)
-
-            canvas = cls.FigureCanvas(figure, master=window)
-            manager = cls.FigureManager(canvas, num, window)
-            if mpl.is_interactive():
-                manager.show()
-                canvas.draw_idle()
-            return manager
-
     @staticmethod
     def mainloop():
         managers = Gcf.get_all_fig_managers()
diff --git a/lib/matplotlib/backends/backend_gtk3.py b/lib/matplotlib/backends/backend_gtk3.py
@@ -142,6 +142,11 @@ def __init__(self, figure=None):
         if renderer_init:
             renderer_init()
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        # docstring inherited
+        return FigureManagerGTK3(cls(figure), num)
+
     @_api.deprecated("3.3", alternative="__init__")
     def _renderer_init(self):
         pass
diff --git a/lib/matplotlib/backends/backend_macosx.py b/lib/matplotlib/backends/backend_macosx.py
@@ -32,6 +32,11 @@ def __init__(self, figure):
         _macosx.FigureCanvas.__init__(self, width, height)
         self._dpi_ratio = 1.0
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        # docstring inherited
+        return FigureManagerMac(cls(figure), num)
+
     def _set_device_scale(self, value):
         if self._dpi_ratio != value:
             # Need the new value in place before setting figure.dpi, which
diff --git a/lib/matplotlib/backends/backend_nbagg.py b/lib/matplotlib/backends/backend_nbagg.py
@@ -142,7 +142,20 @@ def remove_comm(self, comm_id):
 
 
 class FigureCanvasNbAgg(FigureCanvasWebAggCore):
-    pass
+    @classmethod
+    def new_manager(cls, figure, num):
+        canvas = cls(figure)
+        manager = FigureManagerNbAgg(canvas, num)
+        if is_interactive():
+            manager.show()
+            figure.canvas.draw_idle()
+
+        def destroy(event):
+            canvas.mpl_disconnect(cid)
+            Gcf.destroy(manager)
+
+        cid = canvas.mpl_connect('close_event', destroy)
+        return manager
 
 
 class CommSocket:
@@ -227,21 +240,6 @@ class _BackendNbAgg(_Backend):
     FigureCanvas = FigureCanvasNbAgg
     FigureManager = FigureManagerNbAgg
 
-    @staticmethod
-    def new_figure_manager_given_figure(num, figure):
-        canvas = FigureCanvasNbAgg(figure)
-        manager = FigureManagerNbAgg(canvas, num)
-        if is_interactive():
-            manager.show()
-            figure.canvas.draw_idle()
-
-        def destroy(event):
-            canvas.mpl_disconnect(cid)
-            Gcf.destroy(manager)
-
-        cid = canvas.mpl_connect('close_event', destroy)
-        return manager
-
     @staticmethod
     def show(block=None):
         ## TODO: something to do when keyword block==False ?
diff --git a/lib/matplotlib/backends/backend_qt5.py b/lib/matplotlib/backends/backend_qt5.py
@@ -233,6 +233,11 @@ def __init__(self, figure=None):
         palette = QtGui.QPalette(QtCore.Qt.white)
         self.setPalette(palette)
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        # docstring inherited
+        return FigureManagerQT(cls(figure), num)
+
     def _update_figure_dpi(self):
         dpi = self._dpi_ratio * self.figure._original_dpi
         self.figure._set_dpi(dpi, forward=False)
diff --git a/lib/matplotlib/backends/backend_wx.py b/lib/matplotlib/backends/backend_wx.py
@@ -7,6 +7,7 @@
 Copyright (C) Jeremy O'Donoghue & John Hunter, 2003-4.
 """
 
+import functools
 import logging
 import math
 import pathlib
@@ -58,6 +59,15 @@ def DEBUG_MSG(string, lvl=3, o=None):
 IDLE_DELAY = 5  # Documented as deprecated as of Matplotlib 3.1.
 
 
+# lru_cache holds a reference to the App and prevents it from being gc'ed.
+@functools.lru_cache()
+def _create_wxapp():
+    wxapp = wx.App(False)
+    wxapp.SetExitOnFrameDelete(True)
+    cbook._setup_new_guiapp()
+    return wxapp
+
+
 def error_msg_wx(msg, parent=None):
     """Signal an error condition with a popup error dialog."""
     dialog = wx.MessageDialog(parent=parent,
@@ -538,6 +548,17 @@ def __init__(self, parent, id, figure=None):
         self.SetBackgroundStyle(wx.BG_STYLE_PAINT)  # Reduce flicker.
         self.SetBackgroundColour(wx.WHITE)
 
+    @classmethod
+    def new_manager(cls, figure, num):
+        # docstring inherited
+        wxapp = wx.GetApp() or _create_wxapp()
+        frame = FigureFrameWx(num, figure, canvas_cls=cls)
+        figmgr = frame.get_figure_manager()
+        if mpl.is_interactive():
+            figmgr.frame.Show()
+            figure.canvas.draw_idle()
+        return figmgr
+
     def Copy_to_Clipboard(self, event=None):
         """Copy bitmap of canvas to system clipboard."""
         bmp_obj = wx.BitmapDataObject()
@@ -899,7 +920,7 @@ def _print_image(self, filename, filetype, *, quality=None):
 
 
 class FigureFrameWx(wx.Frame):
-    def __init__(self, num, fig):
+    def __init__(self, num, fig, *, canvas_cls=FigureCanvasWx):
         # On non-Windows platform, explicitly set the position - fix
         # positioning bug on some Linux platforms
         if wx.Platform == '__WXMSW__':
@@ -912,7 +933,7 @@ def __init__(self, num, fig):
         self.num = num
         _set_frame_icon(self)
 
-        self.canvas = self.get_canvas(fig)
+        self.canvas = canvas_cls(self, -1, fig)
         w, h = map(math.ceil, fig.bbox.size)
         self.canvas.SetInitialSize(wx.Size(w, h))
         self.canvas.SetFocus()
@@ -960,6 +981,7 @@ def _get_toolbar(self):
             toolbar = None
         return toolbar
 
+    @_api.deprecated("3.5")
     def get_canvas(self, fig):
         return FigureCanvasWx(self, -1, fig)
 
@@ -1484,29 +1506,6 @@ def trigger(self, *args, **kwargs):
 class _BackendWx(_Backend):
     FigureCanvas = FigureCanvasWx
     FigureManager = FigureManagerWx
-    _frame_class = FigureFrameWx
-
-    @classmethod
-    def new_figure_manager(cls, num, *args, **kwargs):
-        # Create a wx.App instance if it has not been created so far.
-        wxapp = wx.GetApp()
-        if wxapp is None:
-            wxapp = wx.App(False)
-            wxapp.SetExitOnFrameDelete(True)
-            cbook._setup_new_guiapp()
-            # Retain a reference to the app object so that it does not get
-            # garbage collected.
-            _BackendWx._theWxApp = wxapp
-        return super().new_figure_manager(num, *args, **kwargs)
-
-    @classmethod
-    def new_figure_manager_given_figure(cls, num, figure):
-        frame = cls._frame_class(num, figure)
-        figmgr = frame.get_figure_manager()
-        if mpl.is_interactive():
-            figmgr.frame.Show()
-            figure.canvas.draw_idle()
-        return figmgr
 
     @staticmethod
     def mainloop():
diff --git a/lib/matplotlib/backends/backend_wxagg.py b/lib/matplotlib/backends/backend_wxagg.py
@@ -1,11 +1,14 @@
 import wx
 
+from matplotlib import _api
 from .backend_agg import FigureCanvasAgg
 from .backend_wx import (
     _BackendWx, _FigureCanvasWxBase, FigureFrameWx,
     NavigationToolbar2Wx as NavigationToolbar2WxAgg)
 
 
+@_api.deprecated(
+    "3.4", alternative="FigureFrameWx(..., canvas_cls=FigureCanvasWxAgg)")
 class FigureFrameWxAgg(FigureFrameWx):
     def get_canvas(self, fig):
         return FigureCanvasWxAgg(self, -1, fig)
diff --git a/lib/matplotlib/backends/backend_wxcairo.py b/lib/matplotlib/backends/backend_wxcairo.py
@@ -1,11 +1,14 @@
 import wx.lib.wxcairo as wxcairo
 
+from matplotlib import _api
 from .backend_cairo import cairo, FigureCanvasCairo, RendererCairo
 from .backend_wx import (
     _BackendWx, _FigureCanvasWxBase, FigureFrameWx,
     NavigationToolbar2Wx as NavigationToolbar2WxCairo)
 
 
+@_api.deprecated(
+    "3.5", alternative="FigureFrameWx(..., canvas_cls=FigureCanvasWxCairo)")
 class FigureFrameWxCairo(FigureFrameWx):
     def get_canvas(self, fig):
         return FigureCanvasWxCairo(self, -1, fig)
@@ -44,4 +47,3 @@ def draw(self, drawDC=None):
 @_BackendWx.export
 class _BackendWxCairo(_BackendWx):
     FigureCanvas = FigureCanvasWxCairo
-    _frame_class = FigureFrameWxCairo
