From 0da7740f6549198d4d600769482f29e84db602e3 Mon Sep 17 00:00:00 2001 From: Eric Firing Date: Sat, 16 Jul 2016 14:32:47 -1000 Subject: [PATCH 1/4] STY: make default legend edgecolor gray; add kwargs for edgecolor, facecolor --- lib/matplotlib/legend.py | 31 ++++++++++++++++--------------- lib/matplotlib/rcsetup.py | 2 +- matplotlibrc.template | 10 +++++----- 3 files changed, 22 insertions(+), 21 deletions(-) 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 From aa857adee21c07146741e92dd12d9d8d910cdc4d Mon Sep 17 00:00:00 2001 From: Eric Firing Date: Sat, 16 Jul 2016 19:45:59 -1000 Subject: [PATCH 2/4] Document new kwargs in Axes.legend docstring --- lib/matplotlib/axes/_axes.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) 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 From 5f979debe09b39a10f85b887c1191d3791b41c6d Mon Sep 17 00:00:00 2001 From: Eric Firing Date: Sat, 16 Jul 2016 21:12:03 -1000 Subject: [PATCH 3/4] Document new (and some old) kwargs in Figure.legend --- lib/matplotlib/figure.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) 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 From f8c770ea128feedf792b0afb3ddd22e8499d9c8b Mon Sep 17 00:00:00 2001 From: Eric Firing Date: Wed, 20 Jul 2016 21:24:48 -1000 Subject: [PATCH 4/4] DOC: add api_changes note about 2 new kwargs --- doc/api/api_changes/2016-07-20-EF.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 doc/api/api_changes/2016-07-20-EF.rst 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.