Merge pull request matplotlib#19304 from smartlixx/add-lgend-title-properties

Add legend title font properties

Author: QuLogic

doc/users/next_whats_new/legend_title_fontproperties_kwarg.rst

@@ -0,0 +1,11 @@
+Font properties of legend title are configurable
+------------------------------------------------
+
+Title's font properties can be set via the *title_fontproperties* keyword
+argument, for example:
+
+.. plot::
+
+    fig, ax = plt.subplots(figsize=(4, 3))
+    ax.plot(range(10),label='point')
+    ax.legend(title='Points', title_fontproperties={'family': 'serif', 'size': 20}) 

lib/matplotlib/legend.py

@@ -237,9 +237,17 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 title : str or None
     The legend's title. Default is no title (``None``).
 
+title_fontproperties : None or `matplotlib.font_manager.FontProperties` or dict
+    The font properties of the legend's title. If None (default), the
+    *title_fontsize* argument will be used if present; if *title_fontsize* is
+    also None, the current :rc:`legend.title_fontsize` will be used.
+
 title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', \
 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize`
     The font size of the legend's title.
+    Note: This cannot be combined with *title_fontproperties*. If you want
+    to set the fontsize alongside other font properties, use the *size*
+    parameter in *title_fontproperties*.
 
 borderpad : float, default: :rc:`legend.borderpad`
     The fractional whitespace inside the legend border, in font-size units.
@@ -332,6 +340,7 @@ def __init__(self, parent, handles, labels,
                  bbox_transform=None,  # transform for the bbox
                  frameon=None,  # draw frame
                  handler_map=None,
+                 title_fontproperties=None,  # properties for the legend title
                  ):
         """
         Parameters
@@ -506,11 +515,23 @@ def __init__(self, parent, handles, labels,
         self._set_loc(loc)
         self._loc_used_default = tmp  # ignore changes done by _set_loc
 
-        # figure out title fontsize:
-        if title_fontsize is None:
-            title_fontsize = mpl.rcParams['legend.title_fontsize']
-        tprop = FontProperties(size=title_fontsize)
-        self.set_title(title, prop=tprop)
+        # figure out title font properties:
+        if title_fontsize is not None and title_fontproperties is not None:
+            raise ValueError(
+                "title_fontsize and title_fontproperties can't be specified "
+                "at the same time. Only use one of them. ")
+        title_prop_fp = FontProperties._from_any(title_fontproperties)
+        if isinstance(title_fontproperties, dict):
+            if "size" not in title_fontproperties:
+                title_fontsize = mpl.rcParams["legend.title_fontsize"]
+                title_prop_fp.set_size(title_fontsize)
+        elif title_fontsize is not None:
+            title_prop_fp.set_size(title_fontsize)
+        elif not isinstance(title_fontproperties, FontProperties):
+            title_fontsize = mpl.rcParams["legend.title_fontsize"]
+            title_prop_fp.set_size(title_fontsize)
+
+        self.set_title(title, prop=title_prop_fp)
         self._draggable = None
 
         # set the text color

lib/matplotlib/tests/test_legend.py

@@ -13,6 +13,7 @@
 from matplotlib.legend_handler import HandlerTuple
 import matplotlib.legend as mlegend
 from matplotlib import rc_context
+from matplotlib.font_manager import FontProperties
 
 
 def test_legend_ordereddict():
@@ -544,12 +545,42 @@ def test_window_extent_cached_renderer():
     leg2.get_window_extent()
 
 
-def test_legend_title_fontsize():
+def test_legend_title_fontprop_fontsize():
     # test the title_fontsize kwarg
-    fig, ax = plt.subplots()
-    ax.plot(range(10))
-    leg = ax.legend(title='Aardvark', title_fontsize=22)
-    assert leg.get_title().get_fontsize() == 22
+    plt.plot(range(10))
+    with pytest.raises(ValueError):
+        plt.legend(title='Aardvark', title_fontsize=22,
+                   title_fontproperties={'family': 'serif', 'size': 22})
+
+    leg = plt.legend(title='Aardvark', title_fontproperties=FontProperties(
+                                       family='serif', size=22))
+    assert leg.get_title().get_size() == 22
+
+    fig, axes = plt.subplots(2, 3, figsize=(10, 6))
+    axes = axes.flat
+    axes[0].plot(range(10))
+    leg0 = axes[0].legend(title='Aardvark', title_fontsize=22)
+    assert leg0.get_title().get_fontsize() == 22
+    axes[1].plot(range(10))
+    leg1 = axes[1].legend(title='Aardvark',
+                          title_fontproperties={'family': 'serif', 'size': 22})
+    assert leg1.get_title().get_fontsize() == 22
+    axes[2].plot(range(10))
+    mpl.rcParams['legend.title_fontsize'] = None
+    leg2 = axes[2].legend(title='Aardvark',
+                          title_fontproperties={'family': 'serif'})
+    assert leg2.get_title().get_fontsize() == mpl.rcParams['font.size']
+    axes[3].plot(range(10))
+    leg3 = axes[3].legend(title='Aardvark')
+    assert leg3.get_title().get_fontsize() == mpl.rcParams['font.size']
+    axes[4].plot(range(10))
+    mpl.rcParams['legend.title_fontsize'] = 20
+    leg4 = axes[4].legend(title='Aardvark',
+                          title_fontproperties={'family': 'serif'})
+    assert leg4.get_title().get_fontsize() == 20
+    axes[5].plot(range(10))
+    leg5 = axes[5].legend(title='Aardvark')
+    assert leg5.get_title().get_fontsize() == 20
 
 
 def test_legend_labelcolor_single():