Merged revisions 3984-4000 via svnmerge from

mdboom · mdboom · commit e573c25ea545 · 2007-10-25T14:10:16.000Z
http://matplotlib.svn.sf.net/svnroot/matplotlib/trunk/matplotlib ........ r3991 | efiring | 2007-10-23 17:25:24 -0400 (Tue, 23 Oct 2007) | 2 lines Bugfix: save colorbar axis label so it won't get lost ........ r3999 | efiring | 2007-10-24 18:14:57 -0400 (Wed, 24 Oct 2007) | 2 lines Added ax kwarg to pyplot.colorbar and Figure.colorbar ........ svn path=/branches/transforms/; revision=4001
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:
@@ -155,6 +161,7 @@ def __init__(self, ax, cmap=None,
         self.filled = filled
         self.solids = None
         self.lines = None
+        self.set_label('')
         if cbook.iterable(ticks):
             self.locator = ticker.FixedLocator(ticks, nbins=len(ticks))
         else:
@@ -183,6 +190,7 @@ def draw_all(self):
         self._config_axes(X, Y)
         if self.filled:
             self._add_solids(X, Y, C)
+        self._set_label()
 
     def _config_axes(self, X, Y):
         '''
@@ -220,11 +228,17 @@ def _config_axes(self, X, Y):
             ax.set_xticklabels(ticklabels)
             ax.xaxis.get_major_formatter().set_offset_string(offset_string)
 
-    def set_label(self, label, **kw):
+    def _set_label(self):
         if self.orientation == 'vertical':
-            self.ax.set_ylabel(label, **kw)
+            self.ax.set_ylabel(self._label, **self._labelkw)
         else:
-            self.ax.set_xlabel(label, **kw)
+            self.ax.set_xlabel(self._label, **self._labelkw)
+
+    def set_label(self, label, **kw):
+        self._label = label
+        self._labelkw = kw
+        self._set_label()
+
 
     def _outline(self, X, Y):
         '''
@@ -556,6 +570,10 @@ def notify(self, mappable):
         is changed.
         '''
         cm.ScalarMappable.notify(self, mappable)
+        # We are using an ugly brute-force method: clearing and
+        # redrawing the whole thing.  The problem is that if any
+        # properties have been changed by methods other than the
+        # colorbar methods, those changes will be lost.
         self.ax.cla()
         self.draw_all()
         #if self.vmin != self.norm.vmin or self.vmax != self.norm.vmax:
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -790,9 +790,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
@@ -1081,10 +1081,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
