matplotlib.legend_handler
Default legend handlers.
Important
This is a low-level legend API, which most end users do not need.
We recommend that you are familiar with the legend guide before reading this documentation.
Legend handlers are expected to be a callable object with a following signature.
legend_handler(legend, orig_handle, fontsize, handlebox)
Where legend is the legend itself, orig_handle is the original plot, fontsize is the fontsize in pixels, and handlebox is a OffsetBox instance. Within the call, you should create relevant artists (using relevant properties from the legend and/or orig_handle) and add them into the handlebox. The artists needs to be scaled according to the fontsize (note that the size is in pixel, i.e., this is dpi-scaled value).
This module includes definition of several legend handler classes derived from the base class (HandlerBase) with the following method:
def legend_artist(self, legend, orig_handle, fontsize, handlebox)
- class matplotlib.legend_handler. HandlerBase ( xpad=0.0, ypad=0.0, update_func=None ) [source]
-
A Base class for default legend handlers.
The derived classes are meant to override create_artists method, which has a following signature.:
def create_artists(self, legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans):
The overridden method needs to create artists of the given transform that fits in the given dimension (xdescent, ydescent, width, height) that are scaled by fontsize if necessary.
- adjust_drawing_area ( legend, orig_handle, xdescent, ydescent, width, height, fontsize ) [source]
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- legend_artist ( legend, orig_handle, fontsize, handlebox ) [source]
-
Return the artist that this HandlerBase generates for the given original artist/handle.
- Parameters
-
-
legend
Legend
-
The legend for which these legend artists are being created.
-
orig_handle
matplotlib.artist.Artist
or similar -
The object for which these legend artists are being created.
- fontsize int
-
The fontsize in pixels. The artists being created should be scaled according to the given fontsize.
-
handlebox
matplotlib.offsetbox.OffsetBox
-
The box which has been created to hold this legend entry's artists. Artists created in the
legend_artist
method must be added to this handlebox inside this method.
-
legend
- update_prop ( legend_handle, orig_handle, legend ) [source]
- class matplotlib.legend_handler. HandlerCircleCollection ( yoffsets=None, sizes=None, **kwargs ) [source]
-
Handler for
CircleCollection
s.- Parameters
-
- numpoints int
-
Number of points to show in legend entry.
- yoffsets array of floats
-
Length numpoints list of y offsets for each point in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_collection ( orig_handle, sizes, offsets, transOffset ) [source]
- class matplotlib.legend_handler. HandlerErrorbar ( xerr_size=0.5, yerr_size=None, marker_pad=0.3, numpoints=None, **kwargs ) [source]
-
Handler for Errorbars.
- Parameters
-
- marker_pad float
-
Padding between points in legend entry.
- numpoints int
-
Number of points to show in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- get_err_size ( legend, xdescent, ydescent, width, height, fontsize ) [source]
- class matplotlib.legend_handler. HandlerLine2D ( marker_pad=0.3, numpoints=None, **kw ) [source]
-
Handler for
Line2D
instances.See also
-
HandlerLine2DCompound
-
An earlier handler implementation, which used one artist for the line and another for the marker(s).
- Parameters
-
- marker_pad float
-
Padding between points in legend entry.
- numpoints int
-
Number of points to show in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
-
- class matplotlib.legend_handler. HandlerLine2DCompound ( marker_pad=0.3, numpoints=None, **kwargs ) [source]
-
Original handler for
Line2D
instances, that relies on combining a line-only with a marker-only artist. May be deprecated in the future.- Parameters
-
- marker_pad float
-
Padding between points in legend entry.
- numpoints int
-
Number of points to show in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- class matplotlib.legend_handler. HandlerLineCollection ( marker_pad=0.3, numpoints=None, **kw ) [source]
-
Handler for
LineCollection
instances.- Parameters
-
- marker_pad float
-
Padding between points in legend entry.
- numpoints int
-
Number of points to show in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- get_numpoints ( legend ) [source]
- class matplotlib.legend_handler. HandlerNpoints ( marker_pad=0.3, numpoints=None, **kwargs ) [source]
-
A legend handler that shows numpoints points in the legend entry.
- Parameters
-
- marker_pad float
-
Padding between points in legend entry.
- numpoints int
-
Number of points to show in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerBase
.
- get_numpoints ( legend ) [source]
- get_xdata ( legend, xdescent, ydescent, width, height, fontsize ) [source]
- class matplotlib.legend_handler. HandlerNpointsYoffsets ( numpoints=None, yoffsets=None, **kwargs ) [source]
-
A legend handler that shows numpoints in the legend, and allows them to be individually offset in the y-direction.
- Parameters
-
- numpoints int
-
Number of points to show in legend entry.
- yoffsets array of floats
-
Length numpoints list of y offsets for each point in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- get_ydata ( legend, xdescent, ydescent, width, height, fontsize ) [source]
- class matplotlib.legend_handler. HandlerPatch ( patch_func=None, **kwargs ) [source]
-
Handler for
Patch
instances.- Parameters
-
- patch_func callable, optional
-
The function that creates the legend key artist. patch_func should have the signature:
def patch_func(legend=legend, orig_handle=orig_handle, xdescent=xdescent, ydescent=ydescent, width=width, height=height, fontsize=fontsize)
Subsequently the created artist will have its
update_prop
method called and the appropriate transform will be applied. - **kwargs
-
Keyword arguments forwarded to
HandlerBase
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- class matplotlib.legend_handler. HandlerPathCollection ( yoffsets=None, sizes=None, **kwargs ) [source]
-
Handler for
PathCollection
s, which are used byscatter
.- Parameters
-
- numpoints int
-
Number of points to show in legend entry.
- yoffsets array of floats
-
Length numpoints list of y offsets for each point in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_collection ( orig_handle, sizes, offsets, transOffset ) [source]
- class matplotlib.legend_handler. HandlerPolyCollection ( xpad=0.0, ypad=0.0, update_func=None ) [source]
-
Handler for
PolyCollection
used infill_between
andstackplot
.- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- class matplotlib.legend_handler. HandlerRegularPolyCollection ( yoffsets=None, sizes=None, **kwargs ) [source]
-
Handler for
RegularPolyCollection
s.- Parameters
-
- numpoints int
-
Number of points to show in legend entry.
- yoffsets array of floats
-
Length numpoints list of y offsets for each point in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpoints
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- create_collection ( orig_handle, sizes, offsets, transOffset ) [source]
- get_numpoints ( legend ) [source]
- get_sizes ( legend, orig_handle, xdescent, ydescent, width, height, fontsize ) [source]
- update_prop ( legend_handle, orig_handle, legend ) [source]
- class matplotlib.legend_handler. HandlerStem ( marker_pad=0.3, numpoints=None, bottom=None, yoffsets=None, **kwargs ) [source]
-
Handler for plots produced by
stem
.- Parameters
-
- marker_pad float, default: 0.3
-
Padding between points in legend entry.
- numpoints int, optional
-
Number of points to show in legend entry.
- bottom float, optional
- yoffsets array of floats, optional
-
Length numpoints list of y offsets for each point in legend entry.
- **kwargs
-
Keyword arguments forwarded to
HandlerNpointsYoffsets
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- get_ydata ( legend, xdescent, ydescent, width, height, fontsize ) [source]
- class matplotlib.legend_handler. HandlerStepPatch ( xpad=0.0, ypad=0.0, update_func=None ) [source]
-
Handler for
StepPatch
instances.- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- class matplotlib.legend_handler. HandlerTuple ( ndivide=1, pad=None, **kwargs ) [source]
-
Handler for Tuple.
- Parameters
-
- ndivide int, default: 1
-
The number of sections to divide the legend area into. If None, use the length of the input tuple.
-
pad
float, default:
rcParams["legend.borderpad"]
(default:0.4
) -
Padding in units of fraction of font size.
- **kwargs
-
Keyword arguments forwarded to
HandlerBase
.
- create_artists ( legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans ) [source]
- matplotlib.legend_handler. update_from_first_child ( tgt, src ) [source]
© 2012–2021 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/3.5.1/api/legend_handler_api.html