renamed axesPatch, axesFrame and figurePatch to be less redundant

jdh2358 · jdh2358 · commit 40f24d5af26d · 2008-06-25T22:03:15.000Z
svn path=/trunk/matplotlib/; revision=5674
diff --git a/API_CHANGES b/API_CHANGES
@@ -1,3 +1,10 @@
+Changes for 0.98.x
+==================
+
+* Figure.figurePatch renamed Figure.patch, Axes.axesPatch renamed
+  Axes.patch, Axes.axesFrame renamed Axes.frame, Axes.get_frame, which
+  returns Axes.patch, is deprecated.  Examples and users guide updated
+
 Changes for 0.98.1
 ==================
 
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,8 @@
+2008-06-25 Figure.figurePatch renamed Figure.patch, Axes.axesPatch
+           renamed Axes.patch, Axes.axesFrame renamed Axes.frame,
+           Axes.get_frame, which returns Axes.patch, is deprecated.
+           Examples and users guide updated - JDH
+
 2008-06-25 Fix rendering quality of pcolor - MGD
 
 =================================================================
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -17,15 +17,15 @@ backgrounds transparent when saving, but will not affect the displayed
 image on the screen.  If you need finer grained control, eg you do not
 want full transparency or you to affect the screen displayed version
 as well, you can set the alpha properties directly.  The figure has a
-:class:`matplotlib.patches.Rectangle` instance called *figurePatch*
-and the axes has a Rectangle instance called *axesPatch*.  You can set
+:class:`matplotlib.patches.Rectangle` instance called *patch*
+and the axes has a Rectangle instance called *patch*.  You can set
 any property on them directly (*facecolor*, *edgecolor*, *linewidth*,
 *linestyle*, *alpha*).  Eg::
 
     fig = plt.figure()
-    fig.figurePatch.set_alpha(0.5)
+    fig.patch.set_alpha(0.5)
     ax = fig.add_subplot(111)
-    ax.axesPatch.set_alpha(0.5)
+    ax.patch.set_alpha(0.5)
 
 If you need *all* the figure elements to be transparent, there is
 currently no global alpha setting, but you can set the alpha channel
diff --git a/doc/pyplots/fig_axes_customize_simple.py b/doc/pyplots/fig_axes_customize_simple.py
@@ -3,11 +3,11 @@
 
 # plt.figure creates a matplotlib.figure.Figure instance
 fig = plt.figure()
-rect = fig.figurePatch # a rectangle instance
+rect = fig.patch # a rectangle instance
 rect.set_facecolor('lightgoldenrodyellow')
 
 ax1 = fig.add_axes([0.1, 0.3, 0.4, 0.4])
-rect = ax1.axesPatch
+rect = ax1.patch
 rect.set_facecolor('lightslategray')
 
 
diff --git a/doc/users/artists.rst b/doc/users/artists.rst
@@ -151,9 +151,9 @@ figures.  Likewise, each :class:`~matplotlib.axes.Axes` bounding box
 (the standard white box with black edges in the typical matplotlib
 plot, has a ``Rectangle`` instance that determines the color,
 transparency, and other properties of the Axes.  These instances are
-stored as member variables :attr:`Figure.figurePatch
-<matplotlib.figure.Figure.figurePatch>` and :attr:`Axes.axesPatch
-<matplotlib.axes.Axes.axesPatch>` ("Patch" is a name inherited from
+stored as member variables :attr:`Figure.patch
+<matplotlib.figure.Figure.patch>` and :attr:`Axes.patch
+<matplotlib.axes.Axes.patch>` ("Patch" is a name inherited from
 MATLAB™, and is a 2D "patch" of color on the figure, eg. rectangles,
 circles and polygons).  Every matplotlib ``Artist`` has the following
 properties
@@ -199,7 +199,7 @@ properties mentioned above:
 
 .. sourcecode:: ipython
 
-    In [149]: matplotlib.artist.getp(fig.figurePatch)
+    In [149]: matplotlib.artist.getp(fig.patch)
 	alpha = 1.0
 	animated = False
 	antialiased or aa = True
@@ -261,7 +261,7 @@ The top level container ``Artist`` is the
 :class:`matplotlib.figure.Figure`, and it contains everything in the
 figure.  The background of the figure is a
 :class:`~matplotlib.patches.Rectangle` which is stored in
-:attr:`Figure.figurePatch <matplotlib.figure.Figure.figurePatch>`.  As
+:attr:`Figure.patch <matplotlib.figure.Figure.patch>`.  As
 you add subplots (:meth:`~matplotlib.figure.Figure.add_subplot`) and
 axes (:meth:`~matplotlib.figure.Figure.add_axes`) to the figure
 these will be appended to the :attr:`Figure.axes
@@ -336,7 +336,7 @@ Here is a summary of the Artists the figure contains
 Figure attribute      Description
 ================      ===============================================================
 axes                  A list of Axes instances (includes Subplot)
-figurePatch           The Rectangle background
+patch                 The Rectangle background
 images                A list of FigureImages patches - useful for raw pixel display
 legends               A list of Figure Legend instances (different from Axes.legends)
 lines                 A list of Figure Line2D instances (rarely used, see Axes.lines)
@@ -356,13 +356,13 @@ in a figure with many helper methods to create and add these
 customize the ``Artists`` it contains.  Like the
 :class:`~matplotlib.figure.Figure`, it contains a
 :class:`~matplotlib.patches.Patch`
-:attr:`~matplotlib.axes.Axes.axesPatch` which is a
+:attr:`~matplotlib.axes.Axes.patch` which is a
 :class:`~matplotlib.patches.Rectangle` for Cartesian coordinates and a
 :class:`~matplotlib.patches.Circle` for polar coordinates; this patch
 determines the shape, background and border of the plotting region::
 
     ax = fig.add_subplot(111)
-    rect = ax.axesPatch  # a Rectangle instance
+    rect = ax.patch  # a Rectangle instance
     rect.set_facecolor('green')
 
 When you call a plotting method, eg. the canonical
@@ -511,7 +511,7 @@ Below is a summary of the Artists that the Axes contains
 Axes attribute    Description
 ==============    ======================================
 artists           A list of Artist instances
-axesPatch         Rectangle instance for Axes background
+patch             Rectangle instance for Axes background
 collections       A list of Collection instances
 images            A list of AxesImage
 legends           A list of Legend instances
diff --git a/examples/api/logo2.py b/examples/api/logo2.py
@@ -7,12 +7,12 @@
 figcolor = '#FFFFCC'
 dpi = 80
 fig = plt.figure(figsize=(8, 2),dpi=dpi)
-fig.figurePatch.set_edgecolor(figcolor)
-fig.figurePatch.set_facecolor(figcolor)
+fig.patch.set_edgecolor(figcolor)
+fig.patch.set_facecolor(figcolor)
 
 # the polar bar plot
 ax = fig.add_axes([0.05, 0.05, 0.2, 01], polar=True)
-ax.axesPatch.set_alpha(axalpha)
+ax.patch.set_alpha(axalpha)
 N = 20
 theta = np.arange(0.0, 2*np.pi, 2*np.pi/N) + np.pi
 radii = 10*np.random.rand(N)
@@ -31,7 +31,7 @@
 
 # the histogram
 axhist = fig.add_axes([0.275, 0.075, 0.2, 0.4])
-axhist.axesPatch.set_alpha(axalpha)
+axhist.patch.set_alpha(axalpha)
 mu, sigma = 100, 15
 x = mu + sigma*np.random.randn(10000)
 
diff --git a/examples/pylab_examples/set_and_get.py b/examples/pylab_examples/set_and_get.py
@@ -83,9 +83,9 @@
 getp(l1)
 
 print 'Rectangle setters'
-setp(gca().axesPatch)
+setp(gca().patch)
 print 'Rectangle getters'
-getp(gca().axesPatch)
+getp(gca().patch)
 
 t = title('Hi mom')
 print 'Text setters'
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -815,7 +815,7 @@ def _set_artist_props(self, a):
             a.set_transform(self.transData)
         a.axes = self
 
-    def get_axes_patch(self):
+    def _gen_axes_patch(self):
         """
         Returns the patch used to draw the background of the axes.  It
         is also used as the clipping path for any data elements on the
@@ -878,24 +878,30 @@ def cla(self):
 
         self._set_artist_props(self.title)
 
-        self.axesPatch = self.get_axes_patch()
-        self.axesPatch.set_figure(self.figure)
-        self.axesPatch.set_facecolor(self._axisbg)
-        self.axesPatch.set_edgecolor(rcParams['axes.edgecolor'])
-        self.axesPatch.set_linewidth(rcParams['axes.linewidth'])
-        self.axesPatch.set_transform(self.transAxes)
-
-        self.axesFrame = self.get_axes_patch()
-        self.axesFrame.set_figure(self.figure)
-        self.axesFrame.set_facecolor('none')
-        self.axesFrame.set_edgecolor(rcParams['axes.edgecolor'])
-        self.axesFrame.set_linewidth(rcParams['axes.linewidth'])
-        self.axesFrame.set_transform(self.transAxes)
-        self.axesFrame.set_zorder(2.5)
+        # the patch draws the background of the axes.  we want this to
+        # be below the other artists; the axesPatch name is deprecated
+        self.patch = self.axesPatch = self._gen_axes_patch()
+        self.patch.set_figure(self.figure)
+        self.patch.set_facecolor(self._axisbg)
+        self.patch.set_edgecolor(rcParams['axes.edgecolor'])
+        self.patch.set_linewidth(rcParams['axes.linewidth'])
+        self.patch.set_transform(self.transAxes)
+
+        # the frame draws the border around the axes and we want this
+        # above.  this is a place holder for a more sophisticated
+        # artist that might just draw a left, bottom frame, or a
+        # centered frame, etc the axesFrame name is deprecated
+        self.frame = self.axesFrame = self._gen_axes_patch()
+        self.frame.set_figure(self.figure)
+        self.frame.set_facecolor('none')
+        self.frame.set_edgecolor(rcParams['axes.edgecolor'])
+        self.frame.set_linewidth(rcParams['axes.linewidth'])
+        self.frame.set_transform(self.transAxes)
+        self.frame.set_zorder(2.5)
         self.axison = True
 
-        self.xaxis.set_clip_path(self.axesPatch)
-        self.yaxis.set_clip_path(self.axesPatch)
+        self.xaxis.set_clip_path(self.patch)
+        self.yaxis.set_clip_path(self.patch)
 
 
     def clear(self):
@@ -1211,7 +1217,8 @@ def get_child_artists(self):
 
     def get_frame(self):
         'Return the axes Rectangle frame'
-        return self.axesPatch
+        warnings.warn('use ax.patch instead', DeprecationWarning)
+        return self.patch
 
     def get_legend(self):
         'Return the legend.Legend instance, or None if no legend is defined'
@@ -1271,7 +1278,7 @@ def add_artist(self, a):
         a.set_axes(self)
         self.artists.append(a)
         self._set_artist_props(a)
-        a.set_clip_path(self.axesPatch)
+        a.set_clip_path(self.patch)
         a._remove_method = lambda h: self.artists.remove(h)
 
     def add_collection(self, collection, autolim=True):
@@ -1284,7 +1291,7 @@ def add_collection(self, collection, autolim=True):
             collection.set_label('collection%d'%len(self.collections))
         self.collections.append(collection)
         self._set_artist_props(collection)
-        collection.set_clip_path(self.axesPatch)
+        collection.set_clip_path(self.patch)
         if autolim:
             if collection._paths and len(collection._paths):
                 self.update_datalim(collection.get_datalim(self.transData))
@@ -1296,7 +1303,7 @@ def add_line(self, line):
         lines
         '''
         self._set_artist_props(line)
-        line.set_clip_path(self.axesPatch)
+        line.set_clip_path(self.patch)
 
         self._update_line_limits(line)
         if not line.get_label():
@@ -1317,7 +1324,7 @@ def add_patch(self, p):
         """
 
         self._set_artist_props(p)
-        p.set_clip_path(self.axesPatch)
+        p.set_clip_path(self.patch)
         self._update_patch_limits(p)
         self.patches.append(p)
         p._remove_method = lambda h: self.patches.remove(h)
@@ -1345,7 +1352,7 @@ def add_table(self, tab):
         '''
         self._set_artist_props(tab)
         self.tables.append(tab)
-        tab.set_clip_path(self.axesPatch)
+        tab.set_clip_path(self.patch)
         tab._remove_method = lambda h: self.tables.remove(h)
 
     def relim(self):
@@ -1419,7 +1426,7 @@ def in_axes(self, mouseevent):
         return *True* if the given *mouseevent* (in display coords)
         is in the Axes
         '''
-        return self.axesPatch.contains(mouseevent)[0]
+        return self.patch.contains(mouseevent)[0]
 
     def get_autoscale_on(self):
         """
@@ -1475,7 +1482,7 @@ def draw(self, renderer=None, inframe=False):
         self.apply_aspect(self.get_position(True))
 
         if self.axison and self._frameon:
-            self.axesPatch.draw(renderer)
+            self.patch.draw(renderer)
 
         artists = []
 
@@ -1508,8 +1515,8 @@ def draw(self, renderer=None, inframe=False):
             # respect z-order for now
             renderer.draw_image(
                 round(l), round(b), im, self.bbox,
-                self.axesPatch.get_path(),
-                self.axesPatch.get_transform())
+                self.patch.get_path(),
+                self.patch.get_transform())
 
         artists.extend(self.collections)
         artists.extend(self.patches)
@@ -1529,7 +1536,7 @@ def draw(self, renderer=None, inframe=False):
         if self.legend_ is not None:
             artists.append(self.legend_)
         if self.axison and self._frameon:
-            artists.append(self.axesFrame)
+            artists.append(self.frame)
 
         dsu = [ (a.zorder, i, a) for i, a in enumerate(artists)
                 if not a.get_animated() ]
@@ -1696,7 +1703,7 @@ def set_axis_bgcolor(self, color):
         """
 
         self._axisbg = color
-        self.axesPatch.set_facecolor(color)
+        self.patch.set_facecolor(color)
 
     ### data limits, ticks, tick labels, and formatting
 
@@ -2364,8 +2371,8 @@ def get_children(self):
             children.append(self.legend_)
         children.extend(self.collections)
         children.append(self.title)
-        children.append(self.axesPatch)
-        children.append(self.axesFrame)
+        children.append(self.patch)
+        children.append(self.frame)
         return children
 
     def contains(self,mouseevent):
@@ -2375,7 +2382,7 @@ def contains(self,mouseevent):
         """
         if callable(self._contains): return self._contains(self,mouseevent)
 
-        inside = self.axesPatch.contains(mouseevent.x, mouseevent.y)
+        inside = self.patch.contains(mouseevent.x, mouseevent.y)
         return inside,{}
 
     def pick(self, *args):
@@ -2647,7 +2654,7 @@ def annotate(self, *args, **kwargs):
         a = mtext.Annotation(*args, **kwargs)
         a.set_transform(mtransforms.IdentityTransform())
         self._set_artist_props(a)
-        if kwargs.has_key('clip_on'):  a.set_clip_path(self.axesPatch)
+        if kwargs.has_key('clip_on'):  a.set_clip_path(self.patch)
         self.texts.append(a)
         return a
     annotate.__doc__ = cbook.dedent(annotate.__doc__) % martist.kwdocd
@@ -5342,7 +5349,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
         im.set_data(X)
         im.set_alpha(alpha)
         self._set_artist_props(im)
-        im.set_clip_path(self.axesPatch)
+        im.set_clip_path(self.patch)
         #if norm is None and shape is None:
         #    im.set_clim(vmin, vmax)
         if vmin is not None or vmax is not None:
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
