Added ax kwarg to pyplot.colorbar and Figure.colorbar

efiring · efiring · commit 0e8027e8ac32 · 2007-10-24T22:14:57.000Z
svn path=/trunk/matplotlib/; revision=3999
diff --git a/API_CHANGES b/API_CHANGES
@@ -1,6 +1,11 @@
-    Changed cbook.reversed so it yields a tuple rather than a 
+    Added ax kwarg to pyplot.colorbar and Figure.colorbar so that
+    one can specify the axes object from which space for the colorbar
+    is to be taken, if one does not want to make the colorbar axes
+    manually.
+
+    Changed cbook.reversed so it yields a tuple rather than a
     (index, tuple). This agrees with the python reversed builtin,
-    and cbook only defines reversed if python doesnt provide the 
+    and cbook only defines reversed if python doesnt provide the
     builtin.
 
     Made skiprows=1 the default on csv2rec
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,5 @@
+2007-10-24 Added ax kwarg to Figure.colorbar and pyplot.colorbar - EF
+
 2007-10-19 Removed a gsave/grestore pair surrounding _draw_ps, which
            was causing a loss graphics state info (see "EPS output
            problem - scatter & edgecolors" on mpl-dev, 2007-10-29)
@@ -12,7 +14,7 @@
            unit/ellipse_compare.py to compare spline with vertex
            approx for both aspects. JDH
 
-2007-10-05 remove generator expressions from texmanager and mpltraits. 
+2007-10-05 remove generator expressions from texmanager and mpltraits.
            generator expressions are not supported by python-2.3 - DSD
 
 2007-10-01 Made matplotlib.use() raise an exception if called after
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -70,21 +70,27 @@
 colorbar_doc = '''
 Add a colorbar to a plot.
 
-Function signatures:
+Function signatures for the pyplot interface; all but the first are
+also method signatures for the Figure.colorbar method:
 
     colorbar(**kwargs)
-
     colorbar(mappable, **kwargs)
+    colorbar(mappable, cax=cax, **kwargs)
+    colorbar(mappable, ax=ax, **kwargs)
+
+    arguments:
+        mappable: the image, ContourSet, etc. to which the colorbar applies;
+                    this argument is mandatory for the Figure.colorbar
+                    method but optional for the pyplot.colorbar function,
+                    which sets the default to the current image.
 
-    colorbar(mappable, cax, **kwargs)
+    keyword arguments:
+        cax: None | axes object into which the colorbar will be drawn
+        ax:  None | parent axes object from which space for a new
+                     colorbar axes will be stolen
 
-The optional arguments mappable and cax may be included in the kwargs;
-they are image, ContourSet, etc. to which the colorbar applies, and
-the axes object in which the colorbar will be drawn.  Defaults are
-the current image and a new axes object created next to that image
-after resizing the image.
 
-kwargs are in two groups:
+**kwargs are in two groups:
     axes properties:
 %s
     colorbar properties:
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -769,9 +769,9 @@ def savefig(self, *args, **kwargs):
 
         self.canvas.print_figure(*args, **kwargs)
 
-    def colorbar(self, mappable, cax=None, **kw):
-        orientation = kw.get('orientation', 'vertical')
-        ax = self.gca()
+    def colorbar(self, mappable, cax=None, ax=None, **kw):
+        if ax is None:
+            ax = self.gca()
         if cax is None:
             cax, kw = cbar.make_axes(ax, **kw)
         cb = cbar.Colorbar(cax, mappable, **kw)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1080,10 +1080,10 @@ def colormaps():
 
 
 from matplotlib.colorbar import colorbar_doc
-def colorbar(mappable = None, cax=None,**kw):
+def colorbar(mappable=None, cax=None, ax=None, **kw):
     if mappable is None:
         mappable = gci()
-    ret = gcf().colorbar(mappable, cax = cax, **kw)
+    ret = gcf().colorbar(mappable, cax = cax, ax=ax, **kw)
     draw_if_interactive()
     return ret
 colorbar.__doc__ = colorbar_doc
