Legend title support

leejjoon · leejjoon · commit cdb9681d0c52 · 2009-02-15T00:12:19.000Z
svn path=/trunk/matplotlib/; revision=6914
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,5 @@
+2009-02-14 Added the legend title support - JJL
+
 2009-02-10 Fixed a bug in backend_pdf so it doesn't break when the setting
            pdf.use14corefonts=True is used. Added test case in
            unit/test_pdf_use14corefonts.py. - NGR
diff --git a/examples/pylab_examples/legend_demo3.py b/examples/pylab_examples/legend_demo3.py
@@ -18,8 +18,8 @@ def myplot(ax):
 
 ax2 = plt.subplot(3,1,2)
 myplot(ax2)
-ax2.legend(loc=1, ncol=2, shadow=True)
-
+ax2.legend(loc=1, ncol=2, shadow=True, title="Legend")
+ax2.get_legend().get_title().set_color("red")
 
 ax3 = plt.subplot(3,1,3)
 myplot(ax3)
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -110,7 +110,8 @@ def __init__(self, parent, handles, labels,
                  mode=None, # mode for horizontal distribution of columns. None, "expand"
 
                  fancybox=None, # True use a fancy box, false use a rounded box, none use rc
-                 shadow = None,
+                 shadow = None, 
+                 title = None, # set a title for the legend
                  ):
         """
         - *parent* : the artist that contains the legend
@@ -135,6 +136,7 @@ def __init__(self, parent, handles, labels,
         handletextpad      the pad between the legend handle and text
         borderaxespad      the pad between the axes and legend border
         columnspacing      the spacing between columns
+        title              the legend title
         ================   ==================================================================
 
 The dimensions of pad and spacing are given as a fraction of the
@@ -276,6 +278,8 @@ def __init__(self, parent, handles, labels,
         # init with null renderer
         self._init_legend_box(handles, labels)
 
+        self.set_title(title)
+
         self._last_fontsize_points = self._fontsize
 
 
@@ -316,6 +320,7 @@ def draw(self, renderer):
 
         renderer.open_group('legend')
 
+
         # find_offset function will be provided to _legend_box and
         # _legend_box will draw itself at the location of the return
         # value of the find_offset.
@@ -562,10 +567,18 @@ def _init_legend_box(self, handles, labels):
 
         sep = self.columnspacing*fontsize
 
-        self._legend_box = HPacker(pad=self.borderpad*fontsize,
-                                   sep=sep, align="baseline",
-                                   mode=mode,
-                                   children=columnbox)
+        self._legend_handle_box = HPacker(pad=0, 
+                                          sep=sep, align="baseline",
+                                          mode=mode,
+                                          children=columnbox)
+
+        self._legend_title_box = TextArea("")
+        
+        self._legend_box = VPacker(pad=self.borderpad*fontsize,
+                                   sep=self.labelspacing*fontsize,
+                                   align="center",
+                                   children=[self._legend_title_box,
+                                             self._legend_handle_box])
 
         self._legend_box.set_figure(self.figure)
 
@@ -640,6 +653,19 @@ def get_texts(self):
         'return a list of text.Text instance in the legend'
         return silent_list('Text', self.texts)
 
+    def set_title(self, title):
+        'set the legend title'
+        self._legend_title_box._text.set_text(title)
+
+        if title:
+            self._legend_title_box.set_visible(True)
+        else:
+            self._legend_title_box.set_visible(False)
+
+    def get_title(self):
+        'return Text instance for the legend title'
+        return self._legend_title_box._text
+
     def get_window_extent(self):
         'return a extent of the the legend'
         return self.legendPatch.get_window_extent()
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -174,6 +174,12 @@ def set_height(self, height):
         """
         self.height = height
 
+    def get_visible_children(self):
+        """
+        Return a list of visible artists it contains.
+        """
+        return [c for c in self._children if c.get_visible()]
+
     def get_children(self):
         """
         Return a list of artists it contains.
@@ -208,7 +214,7 @@ def draw(self, renderer):
 
         px, py = self.get_offset(width, height, xdescent, ydescent)
 
-        for c, (ox, oy) in zip(self.get_children(), offsets):
+        for c, (ox, oy) in zip(self.get_visible_children(), offsets):
             c.set_offset((px+ox, py+oy))
             c.draw(renderer)
 
@@ -281,7 +287,12 @@ def get_extent_offsets(self, renderer):
         pad = self.pad * dpicor
         sep = self.sep * dpicor
 
-        whd_list = [c.get_extent(renderer) for c in self.get_children()]
+        if self.width is not None:
+            for c in self.get_visible_children():
+                if isinstance(c, PackerBase) and c.mode == "expand":
+                    c.set_width(self.width)
+        
+        whd_list = [c.get_extent(renderer) for c in self.get_visible_children()]
         whd_list = [(w, h, xd, (h-yd)) for w, h, xd, yd in whd_list]
 
 
@@ -341,7 +352,7 @@ def get_extent_offsets(self, renderer):
         pad = self.pad * dpicor
         sep = self.sep * dpicor
 
-        whd_list = [c.get_extent(renderer) for c in self.get_children()]
+        whd_list = [c.get_extent(renderer) for c in self.get_visible_children()]
 
         if self.height is None:
             height_descent = max([h-yd for w,h,xd,yd in whd_list])
@@ -520,6 +531,14 @@ def __init__(self, s,
         self._minimumdescent = minimumdescent
 
 
+    def set_text(self, s):
+        "set text"
+        self._text.set_text(s)
+
+    def get_text(self):
+        "get text"
+        return self._text.get_text()
+
     def set_multilinebaseline(self, t):
         """
         Set multilinebaseline .

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+2009-02-14 Added the legend title support - JJL`
	`2`	`+`
`1`	`3`	`2009-02-10 Fixed a bug in backend_pdf so it doesn't break when the setting`
`2`	`4`	`pdf.use14corefonts=True is used. Added test case in`
`3`	`5`	`unit/test_pdf_use14corefonts.py. - NGR`