def __init__(self, parent, handles, labels, loc=None, numpoints=None, # the number of points in the legend line markerscale=None, # the relative size of legend markers # vs. original markerfirst=True, # controls ordering (left-to-right) of # legend marker and label scatterpoints=None, # number of scatter points scatteryoffsets=None, prop=None, # properties for the legend texts fontsize=None, # keyword to set font size directly labelcolor=None, # keyword to set the text color # spacing & pad defined as a fraction of the font-size borderpad=None, # the whitespace inside the legend border labelspacing=None, # the vertical space between the legend # entries handlelength=None, # the length of the legend handles handleheight=None, # the height of the legend handles handletextpad=None, # the pad between the legend handle # and text borderaxespad=None, # the pad between the axes and legend # border columnspacing=None, # spacing between columns ncol=1, # number of columns 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, title=None, # set a title for the legend title_fontsize=None, # the font size for the title 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 frameon=None, # draw frame handler_map=None, ): """ Parameters ---------- parent : `~matplotlib.axes.Axes` or `.Figure` The artist that contains the legend. handles : list of `.Artist` A list of Artists (lines, patches) to be added to the legend. labels : list of str A list of labels to show next to the artists. The length of handles and labels should be the same. If they are not, they are truncated to the smaller of both lengths. Other Parameters ---------------- %(_legend_kw_doc)s Notes ----- Users can specify any arbitrary location for the legend using the *bbox_to_anchor* keyword argument. *bbox_to_anchor* can be a `.BboxBase` (or derived therefrom) or a tuple of 2 or 4 floats. See `set_bbox_to_anchor` for more detail. The legend location can be specified by setting *loc* with a tuple of 2 floats, which is interpreted as the lower-left corner of the legend in the normalized axes coordinate. """ # local import only to avoid circularity from matplotlib.axes import Axes from matplotlib.figure import Figure Artist.__init__(self) if prop is None: if fontsize is not None: self.prop = FontProperties(size=fontsize) else: self.prop = FontProperties( size=mpl.rcParams["legend.fontsize"]) else: self.prop = FontProperties._from_any(prop) if isinstance(prop, dict) and "size" not in prop: self.prop.set_size(mpl.rcParams["legend.fontsize"]) self._fontsize = self.prop.get_size_in_points() self.texts = [] self.legendHandles = [] self._legend_title_box = None #: A dictionary with the extra handler mappings for this Legend #: instance. self._custom_handler_map = handler_map locals_view = locals() for name in ["numpoints", "markerscale", "shadow", "columnspacing", "scatterpoints", "handleheight", 'borderpad', 'labelspacing', 'handlelength', 'handletextpad', 'borderaxespad']: if locals_view[name] is None: value = mpl.rcParams["legend." + name] else: value = locals_view[name] setattr(self, name, value) del locals_view # trim handles and labels if illegal label... _lab, _hand = [], [] for label, handle in zip(labels, handles): if isinstance(label, str) and label.startswith('_'): cbook._warn_external('The handle {!r} has a label of {!r} ' 'which cannot be automatically added to' ' the legend.'.format(handle, label)) else: _lab.append(label) _hand.append(handle) labels, handles = _lab, _hand handles = list(handles) if len(handles) < 2: ncol = 1 self._ncol = ncol if self.numpoints <= 0: raise ValueError("numpoints must be > 0; it was %d" % numpoints) # introduce y-offset for handles of the scatter plot if scatteryoffsets is None: self._scatteryoffsets = np.array([3. / 8., 4. / 8., 2.5 / 8.]) else: self._scatteryoffsets = np.asarray(scatteryoffsets) reps = self.scatterpoints // len(self._scatteryoffsets) + 1 self._scatteryoffsets = np.tile(self._scatteryoffsets, reps)[:self.scatterpoints] # _legend_box is a VPacker instance that contains all # legend items and will be initialized from _init_legend_box() # method. self._legend_box = None if isinstance(parent, Axes): self.isaxes = True self.axes = parent self.set_figure(parent.figure) elif isinstance(parent, Figure): self.isaxes = False self.set_figure(parent) else: raise TypeError("Legend needs either Axes or Figure as parent") self.parent = parent self._loc_used_default = loc is None if loc is None: loc = mpl.rcParams["legend.loc"] if not self.isaxes and loc in [0, 'best']: loc = 'upper right' if isinstance(loc, str): if loc not in self.codes: raise ValueError( "Unrecognized location {!r}. Valid locations are\n\t{}\n" .format(loc, '\n\t'.join(self.codes))) else: loc = self.codes[loc] if not self.isaxes and loc == 0: raise ValueError( "Automatic legend placement (loc='best') not implemented for " "figure legend.") self._mode = mode self.set_bbox_to_anchor(bbox_to_anchor, bbox_transform) # We use FancyBboxPatch to draw a legend frame. The location # and size of the box will be updated during the drawing time. if facecolor is None: facecolor = mpl.rcParams["legend.facecolor"] if facecolor == 'inherit': facecolor = mpl.rcParams["axes.facecolor"] if edgecolor is None: edgecolor = mpl.rcParams["legend.edgecolor"] if edgecolor == 'inherit': edgecolor = mpl.rcParams["axes.edgecolor"] if fancybox is None: fancybox = mpl.rcParams["legend.fancybox"] self.legendPatch = FancyBboxPatch( xy=(0, 0), width=1, height=1, facecolor=facecolor, edgecolor=edgecolor, # If shadow is used, default to alpha=1 (#8943). alpha=(framealpha if framealpha is not None else 1 if shadow else mpl.rcParams["legend.framealpha"]), # The width and height of the legendPatch will be set (in draw()) # to the length that includes the padding. Thus we set pad=0 here. boxstyle=("round,pad=0,rounding_size=0.2" if fancybox else "square,pad=0"), mutation_scale=self._fontsize, snap=True, visible=(frameon if frameon is not None else mpl.rcParams["legend.frameon"]) ) self._set_artist_props(self.legendPatch) # init with null renderer self._init_legend_box(handles, labels, markerfirst) tmp = self._loc_used_default 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) self._draggable = None # set the text color color_getters = { # getter function depends on line or patch 'linecolor': ['get_color', 'get_facecolor'], 'markerfacecolor': ['get_markerfacecolor', 'get_facecolor'], 'mfc': ['get_markerfacecolor', 'get_facecolor'], 'markeredgecolor': ['get_markeredgecolor', 'get_edgecolor'], 'mec': ['get_markeredgecolor', 'get_edgecolor'], } if labelcolor is None: pass elif isinstance(labelcolor, str) and labelcolor in color_getters: getter_names = color_getters[labelcolor] for handle, text in zip(self.legendHandles, self.texts): for getter_name in getter_names: try: color = getattr(handle, getter_name)() text.set_color(color) break except AttributeError: pass elif np.iterable(labelcolor): for text, color in zip(self.texts, itertools.cycle( colors.to_rgba_array(labelcolor))): text.set_color(color) else: raise ValueError("Invalid argument for labelcolor : %s" % str(labelcolor))
def __init__(self, xy, s, size=None, prop=None, _interpolation_steps=1, usetex=False, *args, **kwargs): r""" Create a path from the text. Note that it simply is a path, not an artist. You need to use the `~.PathPatch` (or other artists) to draw this path onto the canvas. Parameters ---------- xy : tuple or array of two float values Position of the text. For no offset, use ``xy=(0, 0)``. s : str The text to convert to a path. size : float, optional Font size in points. Defaults to the size specified via the font properties *prop*. prop : `matplotlib.font_manager.FontProperties`, optional Font property. If not provided, will use a default ``FontProperties`` with parameters from the :ref:`rcParams <matplotlib-rcparams>`. _interpolation_steps : int, optional (Currently ignored) usetex : bool, default: False Whether to use tex rendering. Examples -------- The following creates a path from the string "ABC" with Helvetica font face; and another path from the latex fraction 1/2:: from matplotlib.textpath import TextPath from matplotlib.font_manager import FontProperties fp = FontProperties(family="Helvetica", style="italic") path1 = TextPath((12, 12), "ABC", size=12, prop=fp) path2 = TextPath((0, 0), r"$\frac{1}{2}$", size=12, usetex=True) Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`. """ # Circular import. from matplotlib.text import Text if args or kwargs: cbook.warn_deprecated( "3.1", message="Additional arguments to TextPath used to be " "ignored, but will trigger a TypeError %(removal)s.") if prop is None: prop = FontProperties() else: prop = FontProperties._from_any(prop) if size is None: size = prop.get_size_in_points() self._xy = xy self.set_size(size) self._cached_vertices = None s, ismath = Text(usetex=usetex)._preprocess_math(s) self._vertices, self._codes = text_to_path.get_text_path(prop, s, ismath=ismath) self._should_simplify = False self._simplify_threshold = rcParams['path.simplify_threshold'] self._interpolation_steps = _interpolation_steps