artists. It returns artists that are currently supported by matplotlib.

For matplotlib v1.0 and before, the supported artists are as follows.

* :class:`~matplotlib.lines.Line2D`

* :class:`~matplotlib.patches.Patch`

* :class:`~matplotlib.collections.LineCollection`

* :class:`~matplotlib.collections.RegularPolyCollection`

And, :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` returns

all artists in *ax.lines*, *ax.patches* and

artists in *ax.collection* which are instance of

"_", those artists will be ignored.

Therefore, plots drawn by some *pyplot* commands are not supported by

legend. For example, :func:`~matplotlib.pyplot.fill_between` creates

:class:`~matplotlib.collections.PolyCollection` that is not

supported. Also support is limted for some commands that creat

multiple artists. For example, :func:`~matplotlib.pyplot.errorbar`

creates multiples :class:`~matplotlib.lines.Line2D` instances.

Unfortunately, there is no easy workaround when you need legend for an

artist not supported by matplotlib (You may use one of the supported

artist as a proxy. See below)

In newer version of matplotlib (v1.1 and later), the matplotlib

internals are revised to support

* complex plots that creates multiple artists (e.g., bar, errorbar, etc)

* custom legend handles

See below for details of new functionality.

Legend of Complex Plots

In matplotlib v1.1 (FIXME when released) and later, the legend is

improved to support more plot commands and ease the customization.

Artist Container

The Artist Container is simple class (derived from tuple) that

contains multiple artists. This is introduced primarily to support

legends for complex plot commands that create multiple artists.

Axes instances now have a "containers" attribute (which is a list, and

this is only intended to be used for generating a legend). The items

in this attribute are also returned by

:meth:`~matplotlib.axes.Axes.get_legend_handles_labels`.

For example, "bar" command creates a series of Rectangle

patches. Previously, it returned a list of these patches. With the

current change, it creates a container object of these rectangle

patches (and these patches are added to Axes.patches attribute as

before) and return it instead. As the container class is derived from

a tuple, it should be backward-compatible. Furthermore, the container

object is added to the Axes.containers attributes so that legend

command can properly create a legend for the bar. Thus, you may do ::

or ::

At this time of writing, however, "bar" and "errorbar" are only

supported (hopefully the list will increase). Here is an example.

.. plot:: mpl_examples/pylab_examples/legend_demo4.py

Legend Handler

One of the change is that drawing of legend handles is delegated to

legend handlers. For example, :class:`~matplotlib.lines.Line2D`

instances are handled by

:class:`~matplotlib.legend_handler.HandlerLine2D`. The mapping

between the artists and their corresponding handlers are defined in a

handler_map of the legend. The handler_map is a dictionary of

key-handler pair, where key can be an artist instance or its

class. And the handler is a Handler instance.

Let's consider the following sample code, ::

For each *p_i*, matplotlib

1. check if *p_i* itself is in the handler_map

2. if not, iterate over type(p_i).mro() until a matching key is found in the handler_map

Unless specified, the defaul handler_map is used. Below is a partial

list of key-handler pairs included in the default handler map.

* Line2D : legend_handler.HandlerLine2D()

* Patch : legend_handler.HandlerPatch()

* LineCollection : legend_handler.HandlerLineCollection()

* ...

The legend command takes an optional argument of "handler_map". When

provided, the default handler map will be updated (using dict.update

method) with the provided one. ::

The above example will use *my_handler* for any Line2D

instances (p1 and p2). ::

In the above example, only *p1* will be handled by *my_handler*, while

others will be handled by default handlers.

The curent default handler_map has handlers for errobar and bar

plots. Also, it includes an entry for ¡°tuple¡± which is mapped to

*HandlerTuple*. It simply overplots all the handles for items in the

given tuple. For example,

.. plot::

:include-source:

z = np.random.randn(10)

p1a, = plt.plot(z, "ro", ms=10, mfc="r", mew=2, mec="r") # red filled circle

p1b, = plt.plot(z[:5], "w+", ms=10, mec="w", mew=2) # white cross

plt.legend([p1a, (p1a, p1b)], ["Attr A", "Attr A+B"])

Implement a Custom Handler

Handler can be any callable object with following signature. ::

Where *legend* is the legend itself, *orig_handle* is the original

plot (*p_i* in the above example), *fontsize* is the fontsize in

pixles, and *handlebox* is a OffsetBox instance. Within the call, you

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). See legend_handler.py for more

details.