matplotlib.legend_handler — Matplotlib 3.10.3 documentation (original) (raw)
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 anOffsetBox 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 need to be scaled according to the fontsize (note that the size is in pixels, 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 the 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.
Parameters:
xpadfloat, optional
Padding in x-direction.
ypadfloat, optional
Padding in y-direction.
update_funccallable, optional
Function for updating the legend handler properties from another legend handler, used by update_prop.
adjust_drawing_area(legend, orig_handle, xdescent, ydescent, width, height, fontsize)[source]#
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
legend_artist(legend, orig_handle, fontsize, handlebox)[source]#
Return the artist that this HandlerBase generates for the given original artist/handle.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handlematplotlib.artist.Artist or similar
The object for which these legend artists are being created.
fontsizeint
The fontsize in pixels. The artists being created should be scaled according to the given fontsize.
handleboxOffsetBox
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.
update_prop(legend_handle, orig_handle, legend)[source]#
class matplotlib.legend_handler.HandlerCircleCollection(yoffsets=None, sizes=None, **kwargs)[source]#
Handler for CircleCollections.
Parameters:
numpointsint
Number of points to show in legend entry.
yoffsetsarray 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, offset_transform)[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_padfloat
Padding between points in legend entry.
numpointsint
Number of points to show in legend entry.
**kwargs
Keyword arguments forwarded to HandlerBase.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
get_err_size(legend, xdescent, ydescent, width, height, fontsize)[source]#
class matplotlib.legend_handler.HandlerLine2D(marker_pad=0.3, numpoints=None, **kwargs)[source]#
Handler for Line2D instances.
See also
An earlier handler implementation, which used one artist for the line and another for the marker(s).
Parameters:
marker_padfloat
Padding between points in legend entry.
numpointsint
Number of points to show in legend entry.
**kwargs
Keyword arguments forwarded to HandlerBase.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
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_padfloat
Padding between points in legend entry.
numpointsint
Number of points to show in legend entry.
**kwargs
Keyword arguments forwarded to HandlerBase.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
class matplotlib.legend_handler.HandlerLineCollection(marker_pad=0.3, numpoints=None, **kwargs)[source]#
Handler for LineCollection instances.
Parameters:
marker_padfloat
Padding between points in legend entry.
numpointsint
Number of points to show in legend entry.
**kwargs
Keyword arguments forwarded to HandlerBase.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
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_padfloat
Padding between points in legend entry.
numpointsint
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:
numpointsint
Number of points to show in legend entry.
yoffsetsarray 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_funccallable, 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_propmethod 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]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
class matplotlib.legend_handler.HandlerPathCollection(yoffsets=None, sizes=None, **kwargs)[source]#
Handler for PathCollections, which are used by scatter.
Parameters:
numpointsint
Number of points to show in legend entry.
yoffsetsarray 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, offset_transform)[source]#
class matplotlib.legend_handler.HandlerPolyCollection(xpad=0.0, ypad=0.0, update_func=None)[source]#
Handler for PolyCollection used in fill_between andstackplot.
Parameters:
xpadfloat, optional
Padding in x-direction.
ypadfloat, optional
Padding in y-direction.
update_funccallable, optional
Function for updating the legend handler properties from another legend handler, used by update_prop.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
class matplotlib.legend_handler.HandlerRegularPolyCollection(yoffsets=None, sizes=None, **kwargs)[source]#
Handler for RegularPolyCollections.
Parameters:
numpointsint
Number of points to show in legend entry.
yoffsetsarray 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]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
create_collection(orig_handle, sizes, offsets, offset_transform)[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_padfloat, default: 0.3
Padding between points in legend entry.
numpointsint, optional
Number of points to show in legend entry.
bottomfloat, optional
yoffsetsarray 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]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
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.
Parameters:
xpadfloat, optional
Padding in x-direction.
ypadfloat, optional
Padding in y-direction.
update_funccallable, optional
Function for updating the legend handler properties from another legend handler, used by update_prop.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
class matplotlib.legend_handler.HandlerTuple(ndivide=1, pad=None, **kwargs)[source]#
Handler for Tuple.
Parameters:
ndivideint or None, default: 1
The number of sections to divide the legend area into. If None, use the length of the input tuple.
padfloat, default: [rcParams["legend.borderpad"]](../users/explain/customizing.html?highlight=legend.borderpad#matplotlibrc-sample) (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]#
Return the legend artists generated.
Parameters:
legendLegend
The legend for which these legend artists are being created.
orig_handleArtist or similar
The object for which these legend artists are being created.
xdescent, ydescent, width, heightint
The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsizeint
The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
transTransform
The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.
matplotlib.legend_handler.update_from_first_child(tgt, src)[source]#