diff --git a/doc/api/api_changes/2016-07-20-EF.rst b/doc/api/api_changes/2016-07-20-EF.rst new file mode 100644 index 000000000000..218458711a46 --- /dev/null +++ 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 index 921963c590b3..2fa8bf1a322a 100644 --- 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`. @@ -425,10 +425,24 @@ def legend(self, *args, **kwargs): ``legend.shadow`` :data:`rcParam`. 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`. + 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`. + If ``"inherit"``, it will take the ``axes.facecolor`` + :data:`rcParam`. + + 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`. + If ``"inherit"``, it will take the ``axes.edgecolor`` + :data:`rcParam`. + 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 index fa852e855cc6..080ec98e1926 100644 --- 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`. + *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`. + + *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`. + If ``"inherit"``, it will take the ``axes.facecolor`` + :data:`rcParam`. + + *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`. + If ``"inherit"``, it will take the ``axes.edgecolor`` + :data:`rcParam`. + *ncol* : integer number of columns. default is 1 diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index 65ec29b136a5..d44eb57267a0 100644 --- 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 index 97413692496f..da149164ea6b 100644 --- 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 index ec0978752c24..eea00e1243d2 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -396,13 +396,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