Added doc and cleaned backend_managers, don't want our new file dirty.

OceanWolf · OceanWolf · commit a0d111072f3a · 2015-03-03T15:31:37.000+01:00
diff --git a/doc/api/backend_managers_api.rst b/doc/api/backend_managers_api.rst
@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.backend_managers`
+==================================
+
+.. automodule:: matplotlib.backend_managers
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst
@@ -5,6 +5,7 @@ backends
 .. toctree::
 
    backend_bases_api.rst
+   backend_managers_api.rst
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst
diff --git a/lib/matplotlib/_pylab_helpers.py b/lib/matplotlib/_pylab_helpers.py
@@ -68,6 +68,7 @@ def show_all(cls, block=None):
         it does not block if run inside ipython's "%pylab" mode
         it does not block in interactive mode.
         """
+
         managers = cls.get_all_fig_managers()
         if not managers:
             return
@@ -77,7 +78,7 @@ def show_all(cls, block=None):
 
         if block is not None:
             if block:
-                manager.mainloop()
+                manager._mainloop()
             return
 
         from matplotlib import pyplot
@@ -99,7 +100,7 @@ def show_all(cls, block=None):
             block = False
 
         if not is_interactive() or get_backend() == 'WebAgg':
-            manager.mainloop()
+            manager._mainloop()
 
     @classmethod
     def destroy(cls, num):
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -20,6 +20,12 @@
     pressed, x and y locations in pixel and
     :class:`~matplotlib.axes.Axes` coordinates.
 
+:class:`WindowBase`
+    The base class to display a window.
+
+:class:`MainLoopBase`
+    The base class to start the GUI's main loop.
+
 :class:`ShowBase`
     The base class for the Show class of each interactive backend;
     the 'show' callable is then set to Show.__call__, inherited from
@@ -2503,10 +2509,10 @@ def key_press_handler(event, canvas, toolbar=None):
 
     # quit the figure (defaut key 'ctrl+w')
     if event.key in quit_keys:
-        if isinstance(canvas.manager.mainloop, MainLoopBase): # If new no Gcf.
-            canvas.manager._destroy('window_destroy_event')
-        else:
+        if isinstance(canvas.manager, FigureManagerBase):  # Using old figman.
             Gcf.destroy_fig(canvas.figure)
+        else:
+            canvas.manager._destroy('window_destroy_event')
 
     if toolbar is not None:
         # home or reset mnemonic  (default key 'h', 'home' and 'r')
@@ -2589,6 +2595,14 @@ def __init__(self, name, window):
 
 
 class WindowBase(cbook.EventEmitter):
+    """The base class to show a window on screen.
+
+    Parameters
+    ----------
+    title : str
+        The title of the window.
+    """
+
     def __init__(self, title):
         cbook.EventEmitter.__init__(self)
 
@@ -2602,39 +2616,92 @@ def show(self):
         raise NonGuiException()
 
     def destroy(self):
+        """Destroys the window"""
         pass
 
     def set_fullscreen(self, fullscreen):
+        """Whether to show the window fullscreen or not, GUI only.
+
+        Parameters
+        ----------
+        fullscreen : bool
+            True for yes, False for no.
+        """
         pass
 
-    def set_default_size(self, w, h):
+    def set_default_size(self, width, height):
+        """Sets the default size of the window, defaults to a simple resize.
+
+        Parameters
+        ----------
+        width : int
+            The default width (in pixels) of the window.
+        height : int
+            The default height (in pixels) of the window.
+        """
         self.resize(w, h)
 
-    def resize(self, w, h):
-        """"For gui backends, resize the window (in pixels)."""
+    def resize(self, width, height):
+        """"For gui backends, resizes the window.
+
+        Parameters
+        ----------
+        width : int
+            The new width (in pixels) for the window.
+        height : int
+            The new height (in pixels) for the window.
+        """
         pass
 
     def get_window_title(self):
         """
         Get the title text of the window containing the figure.
         Return None for non-GUI backends (e.g., a PS backend).
+
+        Returns
+        -------
+        str : The window's title.
         """
         return 'image'
 
     def set_window_title(self, title):
         """
         Set the title text of the window containing the figure.  Note that
         this has no effect for non-GUI backends (e.g., a PS backend).
+
+        Parameters
+        ----------
+        title : str
+            The title of the window.
         """
         pass
 
     def add_element_to_window(self, element, expand, fill, pad, side='bottom'):
         """ Adds a gui widget to the window.
-        This has no effect for non-GUI backends
+        This has no effect for non-GUI backends and properties only apply
+        to those backends that support them, or have a suitable workaround.
+
+        Parameters
+        ----------
+        element : A gui element.
+            The element to add to the window
+        expand : bool
+            Whether the element should auto expand to fill as much space within
+            the window as possible.
+        fill : bool
+            If the element can expand, should it make the element bigger,
+            or go into extra padding?  True, False respectfully.
+        pad : int
+            The extra amount of space in pixels to pad the element.
         """
         pass
 
     def destroy_event(self, *args):
+        """Fires this event when the window wants to destroy itself.
+
+        Note this method should hook up to the backend's internal window's
+        close event.
+        """
         s = 'window_destroy_event'
         event = WindowEvent(s, self)
         self._callbacks.process(s, event)
diff --git a/lib/matplotlib/backend_managers.py b/lib/matplotlib/backend_managers.py
@@ -9,17 +9,56 @@
 
 
 class FigureManagerEvent(object):
-    def __init__(self, s, fm):
-        self.name = s
-        self.figure_manager = fm
+    """Event for when something happens to this figure manager.
+    i.e. the figure it controls gets closed
+
+    Attributes
+    ----------
+    signal : str
+        The name of the signal.
+
+    figure_manager : FigureManager
+        The figure manager that fired the event.
+    """
+    def __init__(self, signal, figure_manager):
+        self.name = signal
+        self.figure_manager = figure_manager
 
 
 class FigureManager(cbook.EventEmitter):
+    """
+    The FigureManager creates and wraps the necessary components to display a
+    figure, namely the Window, FigureCanvas and Toolbar.  It gets used whenever
+    you want the figure in a standalone window.
+
+    Parameters
+    ----------
+    figure : `matplotlib.figure.Figure`
+        The figure to manage.
+
+    num : int
+        The figure number.
+
+    Attributes
+    ----------
+
+    canvas : `matplotlib.backend_bases.FigureCanvasBase`
+        The GUI element on which we draw.
+
+    toolbar : `matplotlib.backend_bases.NavigationToolbar2`
+        The toolbar used for interacting with the figure.
+
+    window : `matplotlib.backend_bases.WindowBase`
+        The window that holds the canvas and toolbar.
+
+    num : int
+        The figure number.
+    """
     def __init__(self, figure, num):
         cbook.EventEmitter.__init__(self)
         self.num = num
 
-        self.mainloop = MainLoop()
+        self._mainloop = MainLoop()
         self.window = Window('Figure %d' % num)
         self.window.mpl_connect('window_destroy_event', self._destroy)
 
@@ -63,21 +102,28 @@ def _destroy(self, event=None):
         self._callbacks.process(s, event)
 
     def destroy(self, *args):
+        """Called to destroy this FigureManager, gets called by Gcf through
+        event magic.
+        """
         self.canvas.destroy()
         if self.toolbar:
             self.toolbar.destroy()
         self.window.destroy()
 
-        self.mainloop.__del__()
+        self._mainloop.__del__()
 
     def show(self):
+        """Shows the figure"""
         self.window.show()
 
     def full_screen_toggle(self):
+        """Toggles whether we show fullscreen, alternatively call
+        `window.fullscreen()`"""
         self._full_screen_flag = not self._full_screen_flag
         self.window.set_fullscreen(self._full_screen_flag)
 
     def resize(self, w, h):
+        """"For gui backends, resize the window (in pixels)."""
         self.window.resize(w, h)
 
     def get_window_title(self):
@@ -108,23 +154,3 @@ def show_popup(self, msg):
         Display message in a popup -- GUI only
         """
         pass
-
-
-def new_figure_manager(num, *args, **kwargs):
-    """
-    Create a new figure manager instance
-    """
-    show = kwargs.pop('show', None)
-    if old_new_figure_manager is None:  # Test if we can use the new code
-        FigureClass = kwargs.pop('FigureClass', Figure)
-        thisFig = FigureClass(*args, **kwargs)
-        manager = new_figure_manager_given_figure(num, thisFig)
-    else:  # TODO remove once Gcf removed from backends.  Default to old code.
-        manager = old_new_figure_manager(num, *args, **kwargs)
-        manager.mainloop = MainLoop
-    return manager
-
-
-def new_figure_manager_given_figure(num, figure):
-    manager = FigureManager(figure, num)
-    return manager
diff --git a/lib/matplotlib/backends/__init__.py b/lib/matplotlib/backends/__init__.py
@@ -23,15 +23,16 @@ def get_backends():
     _temp = __import__(backend_name, globals(), locals(),
                        ['Window', 'Toolbar2', 'FigureCanvas', 'MainLoop',
                         'new_figure_manager'], 0)
-    FigureCanvas = _temp.FigureCanvas
     try:
         Window = _temp.Window
         Toolbar2 = _temp.Toolbar2
+        FigureCanvas = _temp.FigureCanvas
         MainLoop = _temp.MainLoop
         old_new_figure_manager = None
     except AttributeError:
         Window = None
         Toolbar2 = None
+        FigureCanvas = None
         MainLoop = getattr(_temp, 'show', do_nothing_show)
         old_new_figure_manager = _temp.new_figure_manager
 
@@ -54,7 +55,7 @@ def pylab_setup():
     
     def do_nothing(*args, **kwargs): pass
     backend_version = getattr(backend_mod,'backend_version', 'unknown')
-    show = None if hasattr(backend_mod, 'show') else do_nothing_show
+    show = getattr(backend_mod, 'show', do_nothing_show)
     draw_if_interactive = getattr(backend_mod, 'draw_if_interactive', do_nothing)
 
     # Additional imports which only happen for certain backends.  This section
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -152,10 +152,10 @@ def show(*args, **kw):
     described above.
     """
     global _show
-    if _show is None:
+    if backend_managers.Window is not None:  # Can we use the new code?
         return _pylab_helpers.Gcf.show_all(*args, **kw)
     else:
-         _show(*args, **kw)
+        _show(*args, **kw)
 
 
 def isinteractive():
@@ -429,14 +429,18 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
         if get_backend().lower() == 'ps':
             dpi = 72
 
-        figManager = backend_managers.new_figure_manager(num, figsize=figsize,
-                                                         dpi=dpi,
-                                                         facecolor=facecolor,
-                                                         edgecolor=edgecolor,
-                                                         frameon=frameon,
-                                                         FigureClass=FigureClass,
-                                                         show=_show,
-                                                         **kwargs)
+        if backend_managers.Window is not None:  # Can we use the new code?
+            fig = FigureClass(figsize=figsize, dpi=dpi, facecolor=facecolor,
+                              edgecolor=edgecolor, frameon=frameon, **kwargs)
+            figManager = backend_managers.FigureManager(fig, num)
+        else:
+            figManager = new_figure_manager(num, figsize=figsize,
+                                            dpi=dpi,
+                                            facecolor=facecolor,
+                                            edgecolor=edgecolor,
+                                            frameon=frameon,
+                                            FigureClass=FigureClass,
+                                            **kwargs)
 
         if figLabel:
             figManager.set_window_title(figLabel)
