The legend module defines the Legend class, which is responsible for drawing legends associated with axes and/or figures.
Important
It is unlikely that you would ever create a Legend instance manually. Most users would normally create a legend via the legend()
function. For more details on legends there is also a legend guide.
The Legend class can be considered as a container of legend handles and legend texts. Creation of corresponding legend handles from the plot elements in the axes or figures (e.g., lines, patches, etc.) are specified by the handler map, which defines the mapping between the plot elements and the legend handlers to be used (the default legend handlers are defined in the legend_handler
module). Note that not all kinds of artist are supported by the legend yet by default but it is possible to extend the legend handler's capabilities to support arbitrary objects. See the legend guide for more information.
class matplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')
[source]
Bases: matplotlib.offsetbox.DraggableOffsetBox
Wrapper around a Legend
to support mouse dragging.
Parameters: |
|
---|
artist_picker(legend, evt)
[source]
finalize_offset()
[source]
class matplotlib.legend.Legend(parent, handles, labels, loc=None, numpoints=None, markerscale=None, markerfirst=True, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, borderpad=None, labelspacing=None, handlelength=None, handleheight=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncol=1, mode=None, fancybox=None, shadow=None, title=None, title_fontsize=None, framealpha=None, edgecolor=None, facecolor=None, bbox_to_anchor=None, bbox_transform=None, frameon=None, handler_map=None)
[source]
Bases: matplotlib.artist.Artist
Place a legend on the axes at location loc.
Parameters: |
| ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Other Parameters: |
|
Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be an instance of BboxBase(or its derivatives) 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.
codes = {'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}
contains(event)
[source]
Test whether the artist contains the mouse event.
Returns the truth value and a dictionary of artist specific details of selection, such as which points are contained in the pick radius. See individual artists for details.
draggable(state=None, use_blit=False, update='loc')
[source]
Set the draggable state -- if state is
If draggable is on, you can drag the legend on the canvas with the mouse. The DraggableLegend
helper instance is returned if draggable is on.
The update parameter control which parameter of the legend changes when dragged. If update is "loc", the loc parameter of the legend is changed. If "bbox", the bbox_to_anchor parameter is changed.
draw(renderer)
[source]
Draw everything that belongs to the legend.
draw_frame(b)
[source]
Set draw frame to b.
Parameters: |
|
---|
get_bbox_to_anchor()
[source]
Return the bbox that the legend will be anchored to.
get_children()
[source]
Return a list of child artists.
classmethod get_default_handler_map()
[source]
A class method that returns the default handler map.
get_draggable()
[source]
Return True
if the legend is draggable, False
otherwise.
get_frame_on()
[source]
Get whether the legend box patch is drawn.
static get_legend_handler(legend_handler_map, orig_handle)
[source]
Return a legend handler from legend_handler_map that corresponds to orig_handler.
legend_handler_map should be a dictionary object (that is returned by the get_legend_handler_map method).
It first checks if the orig_handle itself is a key in the legend_hanler_map and return the associated value. Otherwise, it checks for each of the classes in its method-resolution-order. If no matching key is found, it returns None
.
get_legend_handler_map()
[source]
Return the handler map.
get_tightbbox(renderer)
[source]
Like Legend.get_window_extent
, but uses the box for the legend.
Parameters: |
|
---|---|
Returns: |
|
get_window_extent(renderer=None)
[source]
Return extent of the legend.
set_bbox_to_anchor(bbox, transform=None)
[source]
Set the bbox that the legend will be anchored to.
bbox can be
BboxBase
instance(left, bottom, width, height)
in the given transform (normalized axes coordinate if None)(left, bottom)
where the width and height will be assumed to be zero.classmethod set_default_handler_map(handler_map)
[source]
A class method to set the default handler map.
set_draggable(state, use_blit=False, update='loc')
[source]
Enable or disable mouse dragging support of the legend.
Parameters: |
|
---|---|
Returns: |
|
set_frame_on(b)
[source]
Set whether the legend box patch is drawn.
Parameters: |
|
---|
set_title(title, prop=None)
[source]
Set the legend title. Fontproperties can be optionally set with prop parameter.
classmethod update_default_handler_map(handler_map)
[source]
A class method to update the default handler map.
zorder = 5
This module defines default legend handlers.
It is strongly encouraged to have read the legend guide before 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: |
|
---|
update_prop(legend_handle, orig_handle, legend)
[source]
class matplotlib.legend_handler.HandlerCircleCollection(yoffsets=None, sizes=None, **kw)
[source]
Handler for CircleCollections
.
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, **kw)
[source]
Handler for Errorbars.
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.
Parameters: |
|
---|
Any other keyword arguments are given 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: |
|
---|
Any other keyword arguments are given 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, **kw)
[source]
A legend handler that shows numpoints points in the legend entry.
Parameters: |
|
---|
Any other keyword arguments are given to HandlerBase
.
get_numpoints(legend)
[source]
get_xdata(legend, xdescent, ydescent, width, height, fontsize)
[source]
class matplotlib.legend_handler.HandlerNpointsYoffsets(numpoints=None, yoffsets=None, **kw)
[source]
A legend handler that shows numpoints in the legend, and allows them to be individually offest in the y-direction.
Parameters: |
|
---|
Any other keyword arguments are given to HandlerNpoints
.
get_ydata(legend, xdescent, ydescent, width, height, fontsize)
[source]
class matplotlib.legend_handler.HandlerPatch(patch_func=None, **kw)
[source]
Handler for Patch
instances.
Parameters: |
|
---|
Any other keyword arguments are given to HandlerBase
.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)
[source]
class matplotlib.legend_handler.HandlerPathCollection(yoffsets=None, sizes=None, **kw)
[source]
Handler for PathCollections
, which are used by scatter
.
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 in fill_between
and stackplot
.
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)
[source]
class matplotlib.legend_handler.HandlerRegularPolyCollection(yoffsets=None, sizes=None, **kw)
[source]
Handler for RegularPolyCollections
.
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, **kw)
[source]
Handler for plots produced by stem
.
Parameters: |
|
---|
Any other keyword arguments are given 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.HandlerTuple(ndivide=1, pad=None, **kwargs)
[source]
Handler for Tuple.
Additional kwargs are passed through to HandlerBase
.
Parameters: |
|
---|
create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)
[source]
matplotlib.legend_handler.update_from_first_child(tgt, src)
[source]
© 2012–2018 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/3.0.0/api/legend_api.html