Merge pull request #6770 from efiring/legend_boundary

tacaswell · web-flow · commit 55988531ab08 · 2016-07-25T15:07:46.000-04:00
STY: make default legend edgecolor gray
diff --git a/doc/api/api_changes/2016-07-20-EF.rst b/doc/api/api_changes/2016-07-20-EF.rst
@@ -0,0 +1,10 @@
+`Legend` initializers gain edgecolor and facecolor kwargs
+``````````````````````````````````````````````````````````
+
+The :class:`~matplotlib.legend.Legend` background patch (or 'frame')
+can have its `edgecolor` and `facecolor` determined by the
+corresponding keyword arguments to its initializer, or to any of the
+methods or functions that call that initializer.  If left to
+their default values of `None`, their values will be taken from
+`rcParams`.  The previously-existing `framealpha` kwarg still
+controls the alpha transparency of the patch.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -408,7 +408,7 @@ def legend(self, *args, **kwargs):
             label
 
         frameon : None or bool
-            Control whether a frame should be drawn around the legend.
+            Control whether the legend should be drawn on a patch (frame).
             Default is ``None`` which will take the value from the
             ``legend.frameon`` :data:`rcParam<matplotlib.rcParams>`.
 
@@ -425,10 +425,24 @@ def legend(self, *args, **kwargs):
             ``legend.shadow`` :data:`rcParam<matplotlib.rcParams>`.
 
         framealpha : None or float
-            Control the alpha transparency of the legend's frame.
+            Control the alpha transparency of the legend's background.
             Default is ``None`` which will take the value from the
             ``legend.framealpha`` :data:`rcParam<matplotlib.rcParams>`.
 
+        facecolor : None or "inherit" or a color spec
+            Control the legend's background color.
+            Default is ``None`` which will take the value from the
+            ``legend.facecolor`` :data:`rcParam<matplotlib.rcParams>`.
+            If ``"inherit"``, it will take the ``axes.facecolor``
+            :data:`rcParam<matplotlib.rcParams>`.
+
+        edgecolor : None or "inherit" or a color spec
+            Control the legend's background patch edge color.
+            Default is ``None`` which will take the value from the
+            ``legend.edgecolor`` :data:`rcParam<matplotlib.rcParams>`.
+            If ``"inherit"``, it will take the ``axes.edgecolor``
+            :data:`rcParam<matplotlib.rcParams>`.
+
         mode : {"expand", None}
             If `mode` is set to ``"expand"`` the legend will be horizontally
             expanded to fill the axes area (or `bbox_to_anchor` if defines
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1206,12 +1206,36 @@ def legend(self, handles, labels, *args, **kwargs):
             if *False*, legend marker is placed to the right of the legend
             label
 
+          *frameon*: [ *None* | bool ]
+            Control whether the legend should be drawn on a patch (frame).
+            Default is *None* which will take the value from the
+            ``legend.frameon`` :data:`rcParam<matplotlib.rcParams>`.
+
           *fancybox*: [ *None* | *False* | *True* ]
             if *True*, draw a frame with a round fancybox.  If *None*, use rc
 
           *shadow*: [ *None* | *False* | *True* ]
             If *True*, draw a shadow behind legend. If *None*, use rc settings.
 
+          *framealpha*: [ *None* | float ]
+            Control the alpha transparency of the legend's background.
+            Default is *None* which will take the value from the
+            ``legend.framealpha`` :data:`rcParam<matplotlib.rcParams>`.
+
+          *facecolor*: [ *None* | "inherit" | a color spec ]
+            Control the legend's background color.
+            Default is *None* which will take the value from the
+            ``legend.facecolor`` :data:`rcParam<matplotlib.rcParams>`.
+            If ``"inherit"``, it will take the ``axes.facecolor``
+            :data:`rcParam<matplotlib.rcParams>`.
+
+          *edgecolor*: [ *None* | "inherit" | a color spec ]
+            Control the legend's background patch edge color.
+            Default is *None* which will take the value from the
+            ``legend.edgecolor`` :data:`rcParam<matplotlib.rcParams>`.
+            If ``"inherit"``, it will take the ``axes.edgecolor``
+            :data:`rcParam<matplotlib.rcParams>`.
+
           *ncol* : integer
             number of columns. default is 1
 
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -180,6 +180,8 @@ def __init__(self, parent, handles, labels,
                  title=None,  # set a title for the legend
 
                  framealpha=None,  # set frame alpha
+                 edgecolor=None,  # frame patch edgecolor
+                 facecolor=None,  # frame patch facecolor
 
                  bbox_to_anchor=None,  # bbox that the legend will be anchored.
                  bbox_transform=None,  # transform for the bbox
@@ -197,21 +199,20 @@ def __init__(self, parent, handles, labels,
         ================   ====================================================
         Keyword            Description
         ================   ====================================================
-        loc                a location code
+        loc                Location code string, or tuple (see below).
         prop               the font property
         fontsize           the font size (used only if prop is not specified)
         markerscale        the relative size of legend markers vs. original
-        markerfirst        If true, place legend marker to left of label
-                           If false, place legend marker to right of label
+        markerfirst        If True (default), marker is to left of the label.
         numpoints          the number of points in the legend for line
         scatterpoints      the number of points in the legend for scatter plot
         scatteryoffsets    a list of yoffsets for scatter symbols in legend
-        frameon            if True, draw a frame around the legend.
-                           If None, use rc
-        fancybox           if True, draw a frame with a round fancybox.
-                           If None, use rc
-        shadow             if True, draw a shadow behind legend
-        framealpha         If not None, alpha channel for the frame.
+        frameon            If True, draw the legend on a patch (frame).
+        fancybox           If True, draw the frame with a round fancybox.
+        shadow             If True, draw a shadow behind legend.
+        framealpha         Transparency of the frame.
+        edgecolor          Frame edgecolor.
+        facecolor          Frame facecolor.
         ncol               number of columns
         borderpad          the fractional whitespace inside the legend border
         labelspacing       the vertical space between the legend entries
@@ -345,15 +346,15 @@ def __init__(self, parent, handles, labels,
         # We use FancyBboxPatch to draw a legend frame. The location
         # and size of the box will be updated during the drawing time.
 
-        if rcParams["legend.facecolor"] == 'inherit':
-            facecolor = rcParams["axes.facecolor"]
-        else:
+        if facecolor is None:
             facecolor = rcParams["legend.facecolor"]
+        if facecolor == 'inherit':
+            facecolor = rcParams["axes.facecolor"]
 
-        if rcParams["legend.edgecolor"] == 'inherit':
-            edgecolor = rcParams["axes.edgecolor"]
-        else:
+        if edgecolor is None:
             edgecolor = rcParams["legend.edgecolor"]
+        if edgecolor == 'inherit':
+            edgecolor = rcParams["axes.edgecolor"]
 
         self.legendPatch = FancyBboxPatch(
             xy=(0.0, 0.0), width=1., height=1.,
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1146,7 +1146,7 @@ def validate_hist_bins(s):
     'legend.markerscale': [1.0, validate_float],
     'legend.shadow': [False, validate_bool],
     'legend.facecolor': ['inherit', validate_color_or_inherit],
-    'legend.edgecolor': ['none', validate_color_or_inherit],
+    'legend.edgecolor': ['0.8', validate_color_or_inherit],
 
     # tick properties
     'xtick.top':         [False, validate_bool],   # draw ticks on the top side
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -404,13 +404,13 @@ backend      : $TEMPLATE_BACKEND
 
 ### Legend
 #legend.loc           : best
-#legend.frameon       : True     # whether or not to draw a frame around legend
-#legend.framealpha    : 0.8      # legend frame transparency
+#legend.frameon       : True     # if True, draw the legend on a background patch
+#legend.framealpha    : 0.8      # legend patch transparency
 #legend.facecolor     : inherit  # inherit from axes.facecolor; or color spec
-#legend.edgecolor     : none
+#legend.edgecolor     : 0.8      # background patch boundary color
 #legend.fancybox      : True     # if True, use a rounded box for the
-                                 # legend, else a rectangle
-#legend.shadow        : False
+                                 # legend background, else a rectangle
+#legend.shadow        : False    # if True, give background a shadow effect
 #legend.numpoints     : 1        # the number of marker points in the legend line
 #legend.scatterpoints : 1        # number of scatter points
 #legend.markerscale   : 1.0      # the relative size of legend markers vs. original
